@starci/grammar 0.12.3 → 0.12.5

package/README.md

@@ -36,6 +36,25 @@ its root from one place. Heritage does not re-export Common. It exports `heritag
 
 ## Usage
 
+### Button intent
+
+Applications declare `intent` on `Button` and `IconButton`: `commit`, `alternative`, `dismiss`,
+`neutral` or `destructive`. A destructive action may supply `step="entry" | "confirm"`; omitted
+step means entry. The type permits `step` only for destructive intent. The family DNA's `intent`
+mapping derives the variant. Explicit `variant` remains available to Grammar internals and stories.
+The [generated button props catalog](docs/button-intent-props.generated.md) lists the published values.
+
+Collection rows supply item placement automatically. Wrap a custom repeated card in
+`CollectionItem`, or its action slot in `ItemActions`; both preserve the existing DOM. A repeated
+next action resolves to secondary. `ToolbarActions` supplies chrome placement for custom persistent
+toolbars without adding markup. Bars and panel headers supply chrome placement; neutral commands
+are ghost there, while navbar icon actions stay tertiary. The default decision placement makes a
+neutral command outline. Dialogs and drawers restore decision placement inside their surfaces.
+
+Use a `Button` for final destructive confirmation. `AlertDialog` renders dismiss first, focuses it
+on entry, then renders its destructive confirm last. The `Primitives/Button intent` stories show
+the complete placement mapping in light and dark, including destination, pending and skeleton states.
+
 ### App shell
 
 The [app-shell canon](../../knowledge/ui/composition/app-shell.yaml) owns `FE-APP-SHELL-1` through `FE-APP-SHELL-7`.
@@ -45,7 +64,7 @@ The `Compositions/App shell` stories show the fixed shell, grouped sidebar, icon
 - `SidebarItem.badge`, `badgeLabel` and `badgeMax` show and announce unread counts in both sidebar presentations. `SidebarGroup.placement="end"` places settings groups after the main groups and pushes them to the bottom.
 - The collapsed Sidebar uses Grammar's internal `AnchoredTooltip` on hover and focus. HeroUI Tooltip positions the annotation beside the selected collection item and portals it into the same family DOM scope, preserving HeroUI's collection anatomy. `onAction` runs for every activated destination, including the selected item, so a drawer can close consistently.
 - A fixed `WorkspaceShell` frames its `compactHeader` slot as the mobile opener band; pass a client `Drawer` with an ellipsis `IconButton` trigger. The `navigationDrawer` form owns the same band when it supplies the opener.
-- `AvatarButton seed` passes the stable identity id to Grammar's shared `Avatar`, which draws the deterministic local DiceBear image; an uploaded `src` takes precedence.
+- `AvatarButton seed` passes the stable identity id to Grammar's shared `Avatar`, which draws local DiceBear initials whenever `src` is absent; an uploaded `src` takes precedence.
 - `DropdownMenuItem.mark` accepts a decorative identity mark and is mutually exclusive with `iconSource`. A destructive item uses `tone="danger"`.
 
 Compose the interactive shell in a Client Component, where its glyph functions, callbacks and
@@ -78,7 +97,7 @@ import "@starci/grammar/common/styles.css"
 export const App = () => (
   <GrammarRoot theme="system">
     <PageContainer>
-      <SurfaceCard label="Welcome"><Button>Start</Button></SurfaceCard>
+      <SurfaceCard label="Welcome"><Button intent="commit">Start</Button></SurfaceCard>
     </PageContainer>
   </GrammarRoot>
 )
@@ -220,7 +239,7 @@ page of timestamps does not repeatedly interrupt assistive technology. Grammar o
 `Intl.RelativeTimeFormat` for this primitive; other application date display follows FE-DATE.
 
 **DropdownMenu entries.** `entries` is a list of items and sections; the app writes data and no markup, no separator, no
-className and no size. An item takes `id`, `label`, `description`, `shortcut`, `href`, `isDisabled`, `submenu` and:
+className and no size. An item takes `id`, `label`, `description`, `descriptionLines`, `shortcut`, `href`, `isDisabled`, `submenu` and:
 
 - `iconSource`: a glyph component (the app's Heroicons). Grammar draws it in HeroUI's leading position at the canon icon size,
   20px (`size-5`, `Icon` `leading`; the Heroicons rule R93 / FE-ICON). HeroUI's own docs example draws its sample glyph at
@@ -257,7 +276,7 @@ and `Select` are HeroUI's own list-box items (a `Label`, a `Description`, the it
 DescriptionList, Disclosure, ListBox, Pagination, Stepper, Subnav, Tabs, TagGroup, Timeline.
 
 `DataTable.getCellInteraction(row, columnId)` optionally supplies `onAction`, `onDragOver`,
-`onDragLeave`, `onDrop`, `isHighlighted` and `tone` (`neutral` or `muted`). Cells remain semantic
+`onDragLeave` and `onDrop`. Cells remain semantic
 table cells under the existing arrow-key navigation. An actionable cell takes focus itself,
 activates once with Enter/Space or a click on its plain content, and leaves nested controls to
 their own actions. Native drag callbacks receive the actual inner content-frame event (`HTMLDivElement`); the caller owns
@@ -305,21 +324,30 @@ dismissal and focus return.
 shape in any state, no hover effect, a zoom-out on press, a focus ring, and no zoom under
 `prefers-reduced-motion`. `AvatarButton` is a circle-only avatar built on it (an account-menu
 trigger) and `IdentityLockup` a mark beside a title and a muted subtitle with no caret (a workspace
-switcher trigger). All three work as the `trigger` of `DropdownMenu` and `Popover`. `IdentityLockup`'s mark and monogram fallback are transparent, with foreground-colored initials; the mark is an uncropped square by default (`markShape="rounded"` opts in to a
+switcher trigger). All three work as the `trigger` of `DropdownMenu` and `Popover`. `IdentityLockup`'s uploaded mark has a transparent box; without an image it uses Avatar's local DiceBear initials. The mark is an uncropped square by default (`markShape="rounded"` opts in to a
 corner) and `Avatar` takes `shape="square" | "rounded"`.
 
-Personal avatars are circles. Pass the user or identity id as `seed` on `Avatar`, `AvatarButton`
-or each `AvatarGroup` member. Grammar renders the fixed Lorelei DiceBear style chosen by its DNA,
-memoized for that seed with identical server and client output. An uploaded `src` wins; with
-neither `src` nor `seed`, the existing initials fallback remains. Images have `alt=""`; the avatar
-shell carries its name, or `isDecorative` hides it beside a visible name. `AvatarButton` names the
-button and keeps its inner avatar decorative. Apps install and import Grammar; its pinned
-DiceBear runtime dependencies and avatar drawing stay inside the package.
+Personal avatars are circles. `Avatar`, `AvatarButton` and each `AvatarGroup` member render the
+bundled DiceBear `initials` style whenever `src` is absent. Initials use the first and last words
+of `name`: `Tran Minh Khoa` becomes `TK`, and a single word contributes one letter. Pass the user
+or entity id as `seed` for stable colours; otherwise the name determines the colour. Server and
+client render the same local data URI, with no network request. The image follows the requested
+Avatar shape and keeps contrasting text in light and dark themes. Images have `alt=""`; the
+avatar shell carries its name, or `isDecorative` hides it beside a visible name. `AvatarButton`
+names the button and keeps its inner avatar decorative. Apps install and import Grammar; its
+pinned DiceBear runtime dependencies and avatar drawing stay inside the package.
+
+`kind="person" | "agent"` defaults to `person` on `Avatar`, `AvatarButton` and `AvatarGroup` items.
+Agent names are free text and use the same first-and-last-word initials: `Thao Van Mkt` becomes
+`TM`. Agents add a bottom-right bot badge through HeroUI's Badge anchor, with a surface-colour
+ring and `AI` in the accessible name. The badge is hidden below 32px, including group grid cells;
+their initials and accessible identity remain available.
 The package requires Node 22 or newer, as does the pinned DiceBear engine.
 
 ```tsx
 <Avatar name={user.name} seed={user.id} isDecorative />
 <AvatarButton name={user.name} seed={user.id} src={user.avatarUrl} />
+<Avatar name="Thao Van Mkt" seed="agent-1" kind="agent" />
 <AvatarGroup label="Team" items={members.map(user => ({ id: user.id, name: user.name, seed: user.id }))}
   overflowLabel={count => `${count} more members`} />
 ```
@@ -353,32 +381,52 @@ canon's `FE_NESTED_VARIANT` rejects static field variants throughout app code an
 Tabs inside a painted surface. `FE_GRAMMAR_LAYOUT_ONLY` rejects application paint utilities,
 arbitrary paint properties and inline style paint; application CSS carries layout only.
 
-ListBox defaults to `inset="panel"` inside the same context. The list container extends into the
-panel gutter so row content, loading content and section captions align with the header and search
-field without padding wrappers (PADDING-0). Items keep HeroUI's default padding and selection-indicator
-space; row backgrounds extend into the gutter. Outside a surface, the vendor list inset stays;
+ListBox defaults to `inset="panel"` inside the same context. Its box aligns with the panel's search
+field and tabs boxes without negative margins or application padding wrappers (PADDING-0).
+Content keeps HeroUI's list inset and item padding, rounded hover/pressed/selected backgrounds,
+and selection-indicator space, including inside a scrolling panel. Outside a surface, the vendor list inset stays;
 `inset="panel"` also selects the alignment explicitly. Pass flat `items` or named `sections`
 (`ListBoxSection`), with unique item ids across the whole list. `FE_LIST_PANEL_PADDING` rejects
 horizontal padding wrappers around a list or its section caption within the nearest painted Grammar surface.
 Sidebar's expanded and collapsed
 rows also retain HeroUI item padding.
 
+A `ListBoxItem` is `label` (a string: the title, accessible name and typeahead text), optional `description`,
+`leading` (a centred node in a fixed column before the copy, such as an avatar), `trailing` (after it, such as a count) and
+`isDisabled`. Descriptions show one line with an ellipsis by default; `descriptionLines?: 1 | 2 | 3`
+selects the visible line limit. The same prop and default apply to `DropdownMenuItem`, `SidebarItem`
+and the `ListOption` descriptions used by Select and ComboBox. The packaged stylesheet clamps the
+vendor `Description` slot; its full text stays available to assistive technology.
+`ListBoxItem.emphasis="unread"` makes both the label and description strong using the active family's
+DNA. Omit it for a read row, which keeps HeroUI's normal label and muted description.
+Optional `labelLeading` puts a decorative glyph in the title line itself, inside HeroUI's `Label` before the
+text and on its baseline, e.g. a status mark beside an item's name. Both glyph slots are
+`aria-hidden` (A11Y-2), so the name stays `label`; pass an `Icon usage="chip"` to keep the title line's height.
+`ListBox size="sm" | "md" | "lg"` defaults to `md` and reserves a leading column of 2rem, 2.5rem
+or 3rem, respectively, so icons, avatars and group grids keep labels in one column. An item's
+`size` overrides the list's size.
+
 ```tsx
 <SurfaceCard ariaLabel="Conversations">
   <Heading level={2}>Conversations</Heading>
   <SearchField label="Find a conversation" />
   <ListBox label="Conversations" sections={[
-    { id: "recent", label: "Recent", items: [{ id: "team", label: "Design team" }] },
+    { id: "recent", label: "Recent", items: [
+      { id: "team", label: "Design team", description: "Sam: The draft is ready", emphasis: "unread" },
+    ] },
   ]} />
 </SurfaceCard>
 ```
 
 For a conversation or group identity, use `AvatarGroup layout="grid"` (COLLECTION-3, the Zalo
 reference). It is one round Avatar-sized mark at `sm`, `md`, `lg` or `control`: two members split
-the circle, three show one above two, and four use a 2 by 2 grid with a hairline gap. With more
-members, the fourth cell shows `+N` for everyone beyond the first three. Each member uses Avatar's
-uploaded image, `seed` and initials fallback, and accepts the same custom `fallback`. A single
-person uses Avatar. The default `layout="row"` keeps the overlapping member row.
+the circle, three show one above two, and four use a 2 by 2 grid. With five or more
+members, three avatars remain and the fourth cell shows the total member count, such as `5` or `30`.
+Each cell has a ring in the surface colour. Each member uses Avatar's
+uploaded image or bundled DiceBear initials, accepts `seed`, `kind` and a custom uploaded-image `fallback`,
+and the count uses the shared avatar renderer. `overflowLabel` receives the number of hidden members
+in both layouts and names them accessibly; the grid's visible digits show the total. A single
+person uses Avatar. The default `layout="row"` keeps the overlapping member row and its `+N` overflow count.
 
 ## Theming
 

package/dist/.build-stamp.json

@@ -1,9 +1,9 @@
 {
   "schema": "starci/grammar-build-stamp@1",
   "package": "@starci/grammar",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "algorithm": "starci/grammar-source-digest@1",
-  "sourceDigest": "sha256:3aa873b44e3dde843d9ed4dee490afca7a32cefbaba6f9b023943b9b5e7b5ad5",
-  "distDigest": "sha256:a0b7ed5f0ebeb59cc7e048c5fde00debef3c1bc496a70f823274dd20d079ded7",
-  "builtAt": "2026-10-25T16:22:28.270Z"
+  "sourceDigest": "sha256:ffb4788560df9c19f27b314c79227eb27ffeab503001d9dfcef8412143ea8833",
+  "distDigest": "sha256:b3108e47d872028b103de19bdd2249105e1d355a294a22ec845b40e25bec3e70",
+  "builtAt": "2026-10-25T22:28:40.865Z"
 }

package/dist/common/components-avatar-group.css

@@ -16,6 +16,13 @@
         background: var(--surface, Canvas);
     }
 
+    /* Each member and the total-count cell retain a surface ring over uploaded or generated images. */
+    .starci-core-avatar-group-grid > .starci-core-avatar-group-member,
+    .starci-core-avatar-group-grid > .starci-core-avatar-group-count {
+        outline: 1px solid var(--surface, Canvas);
+        outline-offset: -1px;
+    }
+
     .starci-core-avatar-group[data-grammar-avatar-cells="1"] > .starci-core-avatar-group-grid {
         grid-template-columns: minmax(0, 1fr);
         grid-template-rows: minmax(0, 1fr);

package/dist/common/components-forms.css

@@ -45,8 +45,6 @@
     }
 
     .starci-core-field-error {
-        margin: 0;
-        color: var(--danger, CanvasText);
         font-size: 0.75rem;
         font-weight: 600;
         line-height: 1.4;
@@ -142,7 +140,6 @@
     .starci-core-field-skeleton-control > .starci-core-skeleton {
         block-size: 100%;
         aspect-ratio: auto;
-        border-radius: var(--field-radius, calc(var(--radius, 0.5rem) * 1.5));
     }
 
     .starci-core-field-skeleton-control:is([data-grammar-field-skeleton="input"]) { block-size: 2.5rem; }
@@ -160,11 +157,8 @@
 
     /* A checkbox box and a switch track beside their real labels. */
     .starci-core-field-skeleton-control[data-grammar-field-skeleton="choice"] { flex: none; block-size: 1rem; inline-size: 1rem; }
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="choice"] > .starci-core-skeleton { border-radius: 0.25rem; }
     .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"] { flex: none; block-size: 1.25rem; inline-size: 2rem; }
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"] > .starci-core-skeleton { border-radius: 999px; }
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"][data-grammar-switch-size="lg"] { block-size: 2.25rem; inline-size: 4rem; }
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"][data-grammar-switch-size="control"] { block-size: var(--starci-core-control-min-size, 2.75rem); inline-size: 4.875rem; }
+    .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"][data-grammar-switch-size="lg"] { block-size: 1.5rem; inline-size: 3rem; }
 
     .starci-core-field-skeleton-choice-label {
         color: var(--foreground, CanvasText);
@@ -210,8 +204,11 @@
     .starci-core-number-field-group,
     .starci-core-date-group {
         box-sizing: border-box;
+    }
+
+    .starci-core-input-field,
+    .starci-core-combo-box-group {
         min-block-size: var(--starci-core-field-min-height, 2.5rem);
-        border-radius: var(--field-radius, calc(var(--radius, 0.5rem) * 1.5));
     }
 
     /* Owner 2026-10-25: Select has the same 2.5rem field height as Input. */
@@ -227,8 +224,7 @@
      * are never both outlined. The frame keeps the ring for every way focus arrives (`:focus-within`), so keyboard
      * focus stays visible; forced-colors draws it as a system outline on the same frame.
      */
-    :is(.starci-core-search-field-input, .starci-core-number-field-input, .starci-core-combo-box-input):is(:focus, :focus-visible, [data-focused="true"], [data-focus-visible="true"]) {
-        outline: none;
+    .starci-core-combo-box-input:is(:focus, :focus-visible, [data-focused="true"], [data-focus-visible="true"]) {
         box-shadow: none;
     }
 
@@ -250,13 +246,11 @@
         box-sizing: border-box;
         flex: 1 1 0;
         border-radius: inherit;
-        padding-inline: 0.75rem 1.75rem;
         text-overflow: ellipsis;
     }
 
     .starci-core-combo-box-trigger {
         inset-inline-end: 0;
-        padding-inline-end: 0.5rem;
     }
 
     .starci-core-date-input {
@@ -266,8 +260,6 @@
 
     .starci-core-date-range-separator {
         flex-shrink: 0;
-        padding-inline: 0.25rem;
-        color: var(--muted, GrayText);
     }
 
     /* --- List popover (Select, ComboBox) ---
@@ -315,55 +307,7 @@
     }
 
     /*
-     * --- Switch sizes "lg" (the StarCi look) and "control" ---
-     * `lg`: a 4rem by 2.25rem fully round track, a thumb the track height less 0.5rem inset 0.25rem, an optional glyph centred in the
-     * thumb. `control`: the same shape at the shared control height (2.75rem), so a theme switch lines up with the IconButtons and the
-     * avatar of a bar. Keyed on the stamps the component emits (`data-grammar-switch-size`, `data-grammar-switch-thumb`,
-     * `data-grammar-switch-icon`), never on vendor class names. The geometry is `!important` because consumers import this sheet on
-     * either side of `@heroui/styles`, so layer rank cannot decide against the vendor `.switch--*` size rules. The on position is a
-     * margin (as HeroUI's own thumb), the percentage resolving against the track: 100% - thumb - inset.
-     */
-    [data-component="Switch"][data-grammar-switch-size="lg"] {
-        --grammar-switch-height: 2.25rem;
-        --grammar-switch-width: 4rem;
-    }
-
-    [data-component="Switch"][data-grammar-switch-size="control"] {
-        --grammar-switch-height: var(--starci-core-control-min-size, 2.75rem);
-        --grammar-switch-width: 4.875rem;
-    }
-
-    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]) {
-        --grammar-switch-thumb: calc(var(--grammar-switch-height) - 0.5rem);
-    }
-
-    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]) [data-grammar-choice-control="switch"] {
-        block-size: var(--grammar-switch-height) !important;
-        inline-size: var(--grammar-switch-width) !important;
-        border-radius: 9999px !important;
-    }
-
-    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]) [data-grammar-switch-thumb] {
-        block-size: var(--grammar-switch-thumb) !important;
-        inline-size: var(--grammar-switch-thumb) !important;
-        border-radius: 9999px !important;
-        margin-inline-start: 0.25rem !important;
-        align-items: center;
-        justify-content: center;
-    }
-
-    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]):is([data-selected="true"], [aria-checked="true"]) [data-grammar-switch-thumb] {
-        margin-inline-start: calc(100% - var(--grammar-switch-thumb) - 0.25rem) !important;
-    }
-
-    /* The description and error align under the label, past the wider track. */
-    [data-component="Switch"]:is([data-grammar-switch-size="lg"], [data-grammar-switch-size="control"]) > :is([data-slot="description"], [data-slot="field-error"]) {
-        padding-inline-start: calc(var(--grammar-switch-width) + 0.75rem);
-    }
-
-    /*
-     * The thumb glyph box is the canon icon size, not whatever the vendor's thumb container leaves: 20px (size-5, `Icon` `leading`) on `lg`
-     * and `control`, 16px (`chip`) on `md`, whose thumb is 1rem tall. The glyph fills its box, centred in the thumb.
+     * The thumb glyph box is the canon icon size: 20px (size-5, `Icon` `leading`) on `lg`, 16px (`chip`) on `md`. The glyph fills its box, centred in the thumb.
      */
     .starci-core-switch-icon {
         display: inline-flex;
@@ -404,8 +348,6 @@
 
     .starci-core-slider-output {
         color: var(--muted, GrayText);
-        font-size: 0.875rem;
-        font-variant-numeric: tabular-nums;
     }
 
     /* --- SegmentedControl --- */
@@ -459,10 +401,6 @@
         width: 100%;
         margin: 0;
         padding: 0;
-        color: var(--foreground, CanvasText);
-        font-size: 1rem;
-        font-weight: 700;
-        line-height: 1.3;
     }
 
     .starci-core-fieldset-legend + * {
@@ -564,11 +502,6 @@
         overflow-wrap: anywhere;
     }
 
-    /* --- Read-only reads as settled, not as unavailable --- */
-    [data-grammar-field="true"][data-grammar-readonly="true"] :where(.starci-core-combo-box-group, .starci-core-search-field-group, .starci-core-number-field-group, .starci-core-date-group, .starci-core-textarea-control) {
-        background: var(--surface-secondary, var(--field-background, Canvas));
-    }
-
     /*
      * THE 44px TOUCH FLOOR.
      *

package/dist/common/components-list-panel.css

@@ -1,13 +1,42 @@
-/* PADDING-0: align panel content through the container, retaining HeroUI item and header padding. */
+/* PADDING-0: panel list boxes share the field and tabs edge; HeroUI owns list and item padding. */
 @layer starci-grammar-common {
     .grammar-common-root .starci-core-list-box[data-grammar-list-inset="panel"] {
-        /* Row backgrounds extend into the gutter; vendor padding returns their content to the panel edge. */
-        inline-size: calc(100% + 1rem);
-        margin-inline: -0.5rem;
-        padding-inline: 0 !important;
+        inline-size: 100%;
+        margin-inline: 0;
     }
 
-    .grammar-common-root .starci-core-list-box[data-grammar-list-inset="panel"] .starci-core-list-box-empty {
-        padding-inline: 0.5rem;
+    /* owner:item-description-one-line: clamp the vendor Description slot, preserving its text and paint. */
+    .grammar-common-root [data-slot="description"][data-grammar-item-description="true"] {
+        display: -webkit-box;
+        -webkit-box-orient: vertical;
+        -webkit-line-clamp: 1;
+        line-clamp: 1;
+        overflow: hidden;
+        white-space: normal;
+        text-overflow: ellipsis;
+    }
+
+    .grammar-common-root [data-slot="description"][data-grammar-description-lines="2"] {
+        -webkit-line-clamp: 2;
+        line-clamp: 2;
+    }
+
+    .grammar-common-root [data-slot="description"][data-grammar-description-lines="3"] {
+        -webkit-line-clamp: 3;
+        line-clamp: 3;
+    }
+
+    .grammar-common-root [data-grammar-sidebar-copy="true"] {
+        display: flex;
+        flex: 1;
+        flex-direction: column;
+        min-width: 0;
+    }
+
+    .grammar-common-root [data-grammar-item-label="true"] {
+        max-inline-size: 100%;
+        overflow: hidden;
+        white-space: nowrap;
+        text-overflow: ellipsis;
     }
 }