제품 콘텐츠의 Interaction Grammar를 정본화한다

docs/api-reference/affordance.md

@@ -256,6 +256,48 @@ commitAffordance<H extends AffordanceHand>(result: AffordancePreview<H>): Afford
 ```ts
 computeAnchoredFloatingPosition(input: AnchoredFloatingPositionInput): AnchoredFloatingPosition
 ```
+## `contentInteractionAffordance`
+
+```ts
+contentInteractionAffordance(input: ContentInteractionInput): ContentInteractionAffordance
+```
+## `ContentInteractionAffordance`
+
+```ts
+type ContentInteractionAffordance = {
+  readonly role: ContentInteractionRole;
+  readonly phase: ContentInteractionPhase;
+  readonly selected: boolean;
+  readonly primary: boolean;
+  readonly elevated: boolean;
+};
+```
+## `ContentInteractionInput`
+
+```ts
+type ContentInteractionInput =
+  | {
+      readonly role: "content";
+      readonly selected?: boolean;
+      readonly primary?: boolean;
+      readonly active?: boolean;
+      readonly dragging?: boolean;
+    }
+  | {
+      readonly role: "drop-target" | "insertion";
+      readonly active: boolean;
+    };
+```
+## `ContentInteractionPhase`
+
+```ts
+type ContentInteractionPhase = "rest" | "active" | "dragging";
+```
+## `ContentInteractionRole`
+
+```ts
+type ContentInteractionRole = "content" | "drop-target" | "insertion";
+```
 ## `contextMenuAffordance`
 
 ```ts

docs/api-reference/calendar.md

@@ -604,6 +604,11 @@ RangeCalendar(props: { readonly label: string; readonly value: DateRangeValue |
 ```ts
 shiftVisibleDate(visibleDate: string, period: CalendarPeriod, direction: 1 | -1): string
 ```
+## `startOfCalendarWeek`
+
+```ts
+startOfCalendarWeek(date: string): string
+```
 ## `startOfIsoWeek`
 
 ```ts
@@ -650,5 +655,6 @@ visiblePeriodLabel(period: CalendarPeriod, visibleDate: string, options?: Visibl
 type VisiblePeriodLabelOptions = {
   readonly monthNames?: ReadonlyArray<string>;
   readonly weekSeparator?: string;
+  readonly dateStyle?: "iso" | "named";
 };
 ```

docs/api-reference/ui-primitives-react.md

@@ -56,6 +56,38 @@ Command(props: Omit<ButtonHTMLAttributes<HTMLButtonElement>, "title"> & FocusPre
 ```ts
 type CommandKind = "primary" | "secondary" | "danger";
 ```
+## `contentInteractionAttributes`
+
+```ts
+contentInteractionAttributes(input: ContentInteractionInput): ContentInteractionAttributes
+```
+## `ContentInteractionAttributes`
+
+```ts
+type ContentInteractionAttributes = {
+  readonly "data-ui-interaction": "content" | "drop-target" | "insertion";
+  readonly "data-ui-interaction-phase": "rest" | "active" | "dragging";
+  readonly "data-selected"?: "true" | "false";
+  readonly "data-primary"?: "true";
+  readonly "data-elevated"?: "true";
+};
+```
+## `ContentInteractionInput`
+
+```ts
+type ContentInteractionInput =
+  | {
+      readonly role: "content";
+      readonly selected?: boolean;
+      readonly primary?: boolean;
+      readonly active?: boolean;
+      readonly dragging?: boolean;
+    }
+  | {
+      readonly role: "drop-target" | "insertion";
+      readonly active: boolean;
+    };
+```
 ## `ContextualControls`
 
 ```ts
@@ -129,7 +161,7 @@ FileDropRegion(props: Omit<HTMLAttributes<HTMLDivElement>, "onDrop"> & { readonl
 ## `GridCell`
 
 ```ts
-GridCell(props: TdHTMLAttributes<HTMLTableCellElement> & { readonly selected: boolean; readonly focus?: boolean; }): import("<repository>/node_modules/@types/react/jsx-runtime").JSX.Element
+GridCell(props: TdHTMLAttributes<HTMLTableCellElement> & { readonly selected: boolean; readonly primary?: boolean; readonly focus?: boolean; readonly active?: boolean; readonly dragging?: boolean; }): import("<repository>/node_modules/@types/react/jsx-runtime").JSX.Element
 ```
 ## `InteractionHandleBindingOptions`
 
@@ -206,7 +238,7 @@ ProductInspector(props: HTMLAttributes<HTMLDivElement>): ReactNode
 ## `ProductShell`
 
 ```ts
-ProductShell(props: HTMLAttributes<HTMLDivElement> & { readonly toolbar?: ReactNode; readonly toolbarLabel?: string; readonly inspector?: ReactNode; readonly canvasClassName?: string; readonly fill?: boolean; }): ReactNode
+ProductShell(props: HTMLAttributes<HTMLDivElement> & { readonly toolbar?: ReactNode; readonly toolbarLabel?: string; readonly toolbarPresentation?: "attached" | "floating"; readonly inspector?: ReactNode; readonly canvasClassName?: string; readonly fill?: boolean; }): ReactNode
 ```
 ## `ResizeHandle`
 
@@ -241,7 +273,10 @@ SelectableItem<T extends ElementType = "button">(props: SelectableItemProps<T>):
 type SelectableItemProps<T extends ElementType = "button"> = {
   readonly as?: T;
   readonly selected: boolean;
+  readonly primary?: boolean;
   readonly focus?: boolean;
+  readonly active?: boolean;
+  readonly dragging?: boolean;
 } & ControlAffordanceProps & Omit<ComponentPropsWithoutRef<T>, "as" | "data-selected" | "data-focus">;
 ```
 ## `TabOption`

docs/public/ui-primitives.md

@@ -125,12 +125,30 @@ icon button은 독립 역할이 아니므로 공개 primitive가 아닙니다.
 `expanded`와 `controls`를 disclosure ARIA에 연결하며 표현 markup은 Host가
 children으로 구성합니다.
 
-`SelectableItem`은 polymorphic element에 `selected/focus` data state와
+`SelectableItem`은 polymorphic element에 `selected/active/dragging/focus` data state와
 `data-ui-control` styling slot을 제공합니다. role, ARIA selection과 roving focus는
 해당 widget의 semantic primitive 또는 Web Adapter가 소유합니다. 제품별 copy와
 brand token은 Host 책임이지만 최소 hit target, focus-visible, disabled/pressed와
 tooltip 가시성은 UI Primitive styling hook의 불변식입니다.
 
+### Content interaction grammar
+
+제품 콘텐츠의 지속 선택, 순간 누름, 이동, 드롭 대상과 삽입 위치는 하나의 상태
+어휘를 사용합니다. `selected`는 레이아웃을 바꾸지 않는 안쪽 윤곽과 tonal fill,
+`active`는 더 강한 안쪽 피드백, `dragging`은 실제 이동을 뜻하는 elevation을
+추가합니다. 빈 칸은 선택된 콘텐츠가 아니라 `insertion`입니다.
+
+```tsx
+<SelectableItem selected={selected} active={pressed} dragging={moving}>Card</SelectableItem>
+<GridCell selected={selected} active={pressed} dragging={moving}>Cell</GridCell>
+<div {...contentInteractionAttributes({ role: "drop-target", active: over })} />
+<div {...contentInteractionAttributes({ role: "insertion", active: emptySlot })} />
+```
+
+focus-visible outer ring은 이 상태들과 독립이며, reduced motion에서는 상태 정보는
+유지하고 전환 시간만 제거합니다. toolbar의 pressed/toggle, 입력 caret, 브라우저의
+native text selection은 이 콘텐츠 문법에 포함하지 않습니다.
+
 ### `ControlAffordance`
 
 제품은 semantic role을 복제하지 않고 control이 현재 composition에서 어떻게

packages/json-document-affordance/README.md

@@ -48,6 +48,10 @@ useEditing({
 `historyAffordance(snapshot).hand` exposes the typed Undo/Redo availability map
 directly. The editing runtime still owns history state and execution.
 
+`contentInteractionAffordance` is the canonical product-content state model.
+It distinguishes persistent selection, transient active feedback, movement,
+drop targets, and insertion positions without owning DOM or product color.
+
 `createTypeaheadSession`, `createRenameSession`, and `createLineFocusSession`
 own the reusable state that spans several events. Product selection and rename
 Intents remain callbacks supplied by the host.

packages/json-document-affordance/src/content-interaction.ts

@@ -0,0 +1,49 @@
+export type ContentInteractionRole = "content" | "drop-target" | "insertion";
+
+export type ContentInteractionPhase = "rest" | "active" | "dragging";
+
+export type ContentInteractionInput =
+  | {
+      readonly role: "content";
+      readonly selected?: boolean;
+      readonly primary?: boolean;
+      readonly active?: boolean;
+      readonly dragging?: boolean;
+    }
+  | {
+      readonly role: "drop-target" | "insertion";
+      readonly active: boolean;
+    };
+
+export type ContentInteractionAffordance = {
+  readonly role: ContentInteractionRole;
+  readonly phase: ContentInteractionPhase;
+  readonly selected: boolean;
+  readonly primary: boolean;
+  readonly elevated: boolean;
+};
+
+/** Normalizes persistent selection and transient direct-manipulation feedback. */
+export function contentInteractionAffordance(
+  input: ContentInteractionInput,
+): ContentInteractionAffordance {
+  if (input.role !== "content") {
+    return {
+      role: input.role,
+      phase: input.active ? "active" : "rest",
+      selected: false,
+      primary: false,
+      elevated: false,
+    };
+  }
+  const phase = input.dragging ? "dragging" : input.active ? "active" : "rest";
+  const selected = input.selected ?? false;
+  const primary = selected && (input.primary ?? false);
+  return {
+    role: input.role,
+    phase,
+    selected,
+    primary,
+    elevated: phase === "dragging" || primary,
+  };
+}

packages/json-document-affordance/src/index.ts

@@ -24,6 +24,13 @@ export {
 export { createViewportPositionSession } from "./viewport-position.js";
 export { computeAnchoredFloatingPosition } from "./anchored-floating-position.js";
 export { contextualAffordance } from "./contextual.js";
+export { contentInteractionAffordance } from "./content-interaction.js";
+export type {
+  ContentInteractionAffordance,
+  ContentInteractionInput,
+  ContentInteractionPhase,
+  ContentInteractionRole,
+} from "./content-interaction.js";
 export type {
   AnchoredFloatingPosition,
   AnchoredFloatingPositionInput,

packages/json-document-affordance/tests/content-interaction.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "vitest";
+import { contentInteractionAffordance } from "../src/index.js";
+
+describe("contentInteractionAffordance", () => {
+  test("keeps selection persistent while active and dragging phases change", () => {
+    expect(contentInteractionAffordance({ role: "content", selected: true })).toEqual({
+      role: "content", phase: "rest", selected: true, primary: false, elevated: false,
+    });
+    expect(contentInteractionAffordance({ role: "content", selected: true, active: true })).toEqual({
+      role: "content", phase: "active", selected: true, primary: false, elevated: false,
+    });
+    expect(contentInteractionAffordance({ role: "content", selected: true, active: true, dragging: true })).toEqual({
+      role: "content", phase: "dragging", selected: true, primary: false, elevated: true,
+    });
+    expect(contentInteractionAffordance({ role: "content", selected: true, primary: true })).toEqual({
+      role: "content", phase: "rest", selected: true, primary: true, elevated: true,
+    });
+  });
+
+  test("keeps insertion and drop targets distinct from selected content", () => {
+    expect(contentInteractionAffordance({ role: "insertion", active: true })).toEqual({
+      role: "insertion", phase: "active", selected: false, primary: false, elevated: false,
+    });
+    expect(contentInteractionAffordance({ role: "drop-target", active: true })).toEqual({
+      role: "drop-target", phase: "active", selected: false, primary: false, elevated: false,
+    });
+  });
+});

packages/json-document-calendar/src/calendar-month-grid.tsx

@@ -20,6 +20,7 @@ import {
 } from "@interactive-os/json-document-editing";
 import { selectionModeFromModifiers } from "@interactive-os/json-document-react";
 import {
+  contentInteractionAttributes,
   Command,
   ResizeHandle,
   SelectableItem,
@@ -182,6 +183,7 @@ export const CalendarMonthGrid = forwardRef<CalendarMonthGridHandle, CalendarMon
                       classNames={props.classNames}
                       color={props.getEventColor(item.event)}
                       selected={hand.isOccurrenceSelected(item.event.id, item.event.start)}
+                      dragging={hand.selectionDragPreview?.source.points.some((point) => point.eventId === item.event.id) ?? false}
                       primary={hand.isPrimaryOccurrence(item.event.id, item.event.start)}
                       preview={item.event.id === "preview"}
                       onPointerDown={(event) => {
@@ -245,7 +247,7 @@ function MonthDayCell(input: {
       aria-current={cell.date === props.today ? "date" : undefined}
       data-calendar-day={cell.date}
       tabIndex={-1}
-      data-selected={selectedDate === cell.date ? "true" : undefined}
+      {...contentInteractionAttributes({ role: "insertion", active: selectedDate === cell.date })}
       data-ui-affordance={props.affordances.dateCell}
       className={joinClasses(
         props.classNames.day,
@@ -326,6 +328,7 @@ function MonthEvent(props: {
   readonly classNames: CalendarMonthGridClassNames;
   readonly color: string;
   readonly selected: boolean;
+  readonly dragging?: boolean;
   readonly primary: boolean;
   readonly preview?: boolean;
   readonly onPointerDown?: (event: PointerEvent<HTMLElement>) => void;
@@ -338,7 +341,8 @@ function MonthEvent(props: {
     <SelectableItem
       affordance={props.affordance}
       selected={props.selected}
-      data-primary={props.primary ? "true" : undefined}
+      primary={props.primary}
+      {...(props.dragging === undefined ? {} : { dragging: props.dragging })}
       aria-label={calendarEventLabel(props.event)}
       data-calendar-color={props.color}
       data-calendar-move-surface={props.onPointerDown === undefined ? undefined : "true"}

packages/json-document-calendar/src/calendar-time-grid.tsx

@@ -11,7 +11,7 @@ import {
   type CalendarOccurrenceTopologySnapshot,
 } from "@interactive-os/json-document-editing";
 import { selectionModeFromModifiers } from "@interactive-os/json-document-react";
-import { ResizeHandle, SelectableItem, type ControlAffordance } from "@interactive-os/json-document-ui-primitives-react";
+import { contentInteractionAttributes, ResizeHandle, SelectableItem, type ControlAffordance } from "@interactive-os/json-document-ui-primitives-react";
 import { calendarTimeLabel, type CalendarCell } from "./date-values.js";
 import type { CalendarHand } from "./use-calendar-hand.js";
 import type { CalendarPointerInteractions } from "./use-calendar-pointer-interactions.js";
@@ -112,7 +112,7 @@ export function CalendarTimeGrid(props: CalendarTimeGridProps): ReactNode {
     if (start !== null && end !== null) hand.createInterval(start, end);
   }
 
-  const gridColumns = `3.25rem repeat(${days.length}, minmax(4.5rem, 1fr))`;
+  const gridColumns = `4rem repeat(${days.length}, minmax(4.5rem, 1fr))`;
   const gridHeight = (props.hourEnd - props.hourStart) * props.pixelsPerHour;
   return (
     <div
@@ -130,7 +130,7 @@ export function CalendarTimeGrid(props: CalendarTimeGridProps): ReactNode {
         <div className={props.classNames.columnHeader} />
         {props.cells.map((cell) => (
           <div key={cell.date} role="columnheader" className={props.classNames.columnHeader}>
-            <span className={props.classNames.weekday}>{props.weekdays[cell.weekday - 1]}</span>
+            <span className={props.classNames.weekday}>{props.weekdays[cell.weekday % 7]}</span>
             <span className={joinClasses(props.classNames.dayNumber, cell.date === props.today ? props.classNames.today : undefined)}>{cell.day}</span>
           </div>
         ))}
@@ -140,7 +140,7 @@ export function CalendarTimeGrid(props: CalendarTimeGridProps): ReactNode {
             key={`allday-${day}`}
             data-calendar-allday-day={day}
             tabIndex={-1}
-            data-selected={selectedSlot === day ? "true" : undefined}
+            {...contentInteractionAttributes({ role: "insertion", active: selectedSlot === day })}
             data-ui-affordance={props.affordances.allDayCell}
             className={props.classNames.allDayCell}
             style={{ gridRow: `2 / span ${allDayLaneCount}` }}
@@ -162,7 +162,8 @@ export function CalendarTimeGrid(props: CalendarTimeGridProps): ReactNode {
             <SelectableItem
               affordance={props.affordances.allDayEvent}
               selected={hand.isOccurrenceSelected(item.event.id, item.event.start)}
-              data-primary={hand.isPrimaryOccurrence(item.event.id, item.event.start) ? "true" : undefined}
+              primary={hand.isPrimaryOccurrence(item.event.id, item.event.start)}
+              dragging={hand.selectionDragPreview?.source.points.some((point) => point.eventId === item.event.id) ?? false}
               aria-label={item.event.title}
               data-calendar-color={props.getEventColor(item.event)}
               data-calendar-move-surface="true"
@@ -210,8 +211,8 @@ export function CalendarTimeGrid(props: CalendarTimeGridProps): ReactNode {
             className={props.classNames.viewportAnchor}
             style={{ transform: `translateY(${(props.workHourStart - props.hourStart) * props.pixelsPerHour}px)` }}
           />
-          {Array.from({ length: props.hourEnd - props.hourStart }, (_, index) => props.hourStart + index).map((hour) => (
-            <div key={hour} data-calendar-hour={String(hour).padStart(2, "0")} className={props.classNames.hourLabel} style={{ top: (hour - props.hourStart) * props.pixelsPerHour + 4 }}>
+          {Array.from({ length: props.hourEnd - props.hourStart }, (_, index) => index === 0 ? null : props.hourStart + index).map((hour) => hour === null ? null : (
+            <div key={hour} data-calendar-hour={String(hour).padStart(2, "0")} className={props.classNames.hourLabel} style={{ top: (hour - props.hourStart) * props.pixelsPerHour }}>
               {props.labels.hour(hour)}
             </div>
           ))}
@@ -252,6 +253,7 @@ function TimeColumn(input: {
       {input.selectedSlot?.startsWith(`${day}T`) ? (
         <div
           data-calendar-selected-slot={input.selectedSlot}
+          {...contentInteractionAttributes({ role: "insertion", active: true })}
           data-ui-affordance={props.affordances.selectedSlot}
           className={props.classNames.selectedSlot}
           style={{
@@ -288,7 +290,8 @@ function TimeColumn(input: {
             <SelectableItem
               affordance={props.affordances.timedEvent}
               selected={hand.isOccurrenceSelected(item.event.id, item.event.start)}
-              data-primary={hand.isPrimaryOccurrence(item.event.id, item.event.start) ? "true" : undefined}
+              primary={hand.isPrimaryOccurrence(item.event.id, item.event.start)}
+              dragging={hand.selectionDragPreview?.source.points.some((point) => point.eventId === item.event.id) ?? false}
               aria-label={item.event.title}
               data-calendar-event=""
               data-calendar-color={props.getEventColor(item.event)}