@astryxdesign/cli 0.7.12-canary.ccb4a6d → 0.7.12-canary.da3dbdc

package/assets/docs/browser-support.doc.mjs

@@ -148,11 +148,11 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "On a phone, a fully expanded `height='tall'` BottomSheet responds to the on-screen keyboard: it measures the keyboard as the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, it keeps the focused field above the keyboard and leaves the page where it was. If Firefox for Android pans to the field, the sheet puts the page back within a couple of frames.",
+          text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames.",
         },
         {
           type: 'prose',
-          text: 'In Chrome on Android, a Tall BottomSheet\u2019s focused field rides the keyboard as Gboard slides it up, and as Gboard slides it down after the field loses focus. The scroll room stays until the keyboard is down. A hide Chrome reports late, such as Back, which keeps the focus, rides down from Chrome\u2019s report. When the keyboard is reported, the sheet places the field just above it in that same frame, so Chrome has no covered field to pan to; if Chrome pans anyway, the sheet puts the page back when that pan ends. Chrome follows your viewport setting, which Astryx documents and never sets: your app owns its viewport `<meta>` element. By default (`interactive-widget=resizes-visual`) Chrome lays the keyboard over the page and pans to a focused field elsewhere on the page. With `interactive-widget=resizes-content` it shrinks the layout viewport instead, so content anchored to the bottom sits above the keyboard, and the sheet measures no keyboard and changes nothing: the browser has already made the room.',
+          text: 'In Chrome on Android, ChatLayout\u2019s composer rides the keyboard as Gboard slides it up and down. A Tall BottomSheet\u2019s focused field rides the keyboard as Gboard slides it up, and as Gboard slides it down after the field loses focus. The scroll room stays until the keyboard is down. A hide Chrome reports late, such as Back, which keeps the focus, rides down from Chrome\u2019s report. When the keyboard is reported, the sheet places the field just above it in that same frame, so Chrome has no covered field to pan to; if Chrome pans anyway, the sheet puts the page back when that pan ends. Chrome follows your viewport setting, which Astryx documents and never sets: your app owns its viewport `<meta>` element. By default (`interactive-widget=resizes-visual`) Chrome lays the keyboard over the page and pans to a focused field elsewhere on the page. With `interactive-widget=resizes-content` it shrinks the layout viewport instead, so content anchored to the bottom sits above the keyboard, and those components measure no keyboard and change nothing: the browser has already made the room.',
         },
         {
           type: 'code',

package/assets/docs/styling-overview.doc.mjs

@@ -90,7 +90,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          label: 'Install (add to an existing Tailwind v4 app)',
+          label: 'Install',
           code: '{@pm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral}',
         },
         {
@@ -113,7 +113,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',
+          text: 'A project with Tailwind already set up needs a smaller change, which {@link generic:tailwind} shows. For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',
         },
       ],
     },
@@ -160,6 +160,10 @@ export const docs = {
           type: 'prose',
           text: 'If a swizzled component fails at runtime with a `stylex.create` error, the app is missing a StyleX compiler: see the StyleX Build Setup section of {@link generic:tokens-and-setup}.',
         },
+        {
+          type: 'prose',
+          text: "`{@command swizzle <Component>}` writes an `astryx-swizzle.json` marker into an output folder it owns (one the copy creates, an empty one, or one it marked before); every module under that folder then compiles as Astryx source, so keep copies in a folder of their own, such as the default `components/astryx`. For a folder that already holds other files it writes no marker and says how to add one by hand. With `@astryxdesign/build`'s Babel, PostCSS and Vite integrations, or `withAstryx()` under webpack, a copy under that folder compiles into `astryx-base`, below `astryx-theme`, so theme component overrides reach it as they reach the package component. Under Turbopack, and with the stock StyleX plugins above, a copy's rules land in your own styles, above `astryx-theme`, and theme component overrides do not reach it.",
+        },
       ],
     },
     {

package/assets/docs/tree/render-pages.doc.mjs

@@ -57,7 +57,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'What it cannot keep: anything that needs a browser while running. State, effects, click handlers and data loaded after the first paint are gone, and a chart sized by its container is empty, so give charts a fixed size. Read browser-only values such as window inside an effect, or the render stops with ERR_RENDER_BROWSER_API.',
+          text: 'What it cannot keep: anything that needs a browser while running. State, effects, click handlers and data loaded after the first paint are gone. Charts made with recharts are the exception: the render draws each chart and ResponsiveContainer a module of the page (not an installed package) imports from recharts by name (`import {LineChart} from \'recharts\'`), inside the page, so a custom tick, label or shape sees the page\'s React context. A chart sized by its container scales to the width the page gives it, and its legend stays out of the picture: a horizontal legend takes its own row under it (above it when the legend asks for the top), and a vertical legend on one side sits beside it, on that side; in a chart of fixed size, a legend keeps the place its props give it. Charts show the data and props of the page\'s first render, before its effects run: when the page cannot be drawn again without a browser, or its effects change its charts or re-render the component that makes them, each chart is drawn by itself and its parts see React context defaults. A value a chart\'s parts read from a React context that an effect changes may still show its later value. A `chart-size` warning counts the charts the render cannot draw (one used through `import * as R`, say), and says when charts were drawn by themselves. Read browser-only values such as window inside an effect, or the render stops with ERR_RENDER_BROWSER_API.',
         },
       ],
     },
@@ -86,7 +86,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'It writes the page, the modules, stylesheets and JSON files the page reaches through its own imports, and the images, fonts and media the render carried (however the page named them, as long as their bytes really are one): each goes where the page\'s relative imports find it from wherever you put the page, and a file the page imports through a path alias (`@/components/Header`) goes where your project\'s `tsconfig.json` or `jsconfig.json` alias points. Every file but the page goes inside the one new folder the restore creates (the topmost folder on the page\'s path that does not exist yet), never into a folder that already exists: a page that imports other files comes back into a new folder (`--out restored/app/page.tsx`), and a file it imports through a path alias comes back only when that alias points inside the new folder. Nor does it write a file that a test, story or benchmark runner would run by its default patterns (Jest, Vitest, Bun, AVA, Playwright, Storybook, Cypress and `node --test`: names such as `*.test.*`, `*.spec.*`, `*_test.*`, `*-test.*`, `*.bench.*`, `*.stories.*`, `*.cy.*`, and anything under `test/`, `tests/` or `__tests__/`), judged from the repository root (every folder above the file up to it), else the topmost folder with a package.json. Restored files are the sender\'s code: read them before you run or import them. Without `--out`, everything comes back into a new folder beside the HTML file, named after it (`page.html` comes back into `page-restored/`). A received file that carries anything else (a file the page never imports, a dotfile, `package.json`, a tool configuration, a path that leaves the folder) is refused with nothing written. An existing file is never replaced unless you pass `--overwrite`, and the refusal names every one; a generated, vendored or ignored file, and any path through a symbolic link, is not written even then. Add `--json` for the result as data: what was written, how big it is, and every warning.',
+          text: 'It writes the page, the modules, stylesheets and JSON files the page reaches through its own imports, and the images, fonts and media the render carried (however the page named them, as long as their bytes really are one): each goes where the page\'s relative imports find it from wherever you put the page, and a file the page imports through a path alias (`@/components/Header`) goes where your project\'s `tsconfig.json` or `jsconfig.json` alias points. Every file but the page goes inside the one new folder the restore creates (the topmost folder on the page\'s path that does not exist yet), never into a folder that already exists: a page that imports other files comes back into a new folder (`--out restored/app/page.tsx`), and a file it imports through a path alias comes back only when that alias points inside the new folder. Nor does it write a file that a test, story or benchmark runner would run by its default patterns (Jest, Vitest, Bun, AVA, Playwright, Storybook, Cypress and `node --test`: names such as `*.test.*`, `*.spec.*`, `*_test.*`, `*-test.*`, `*.bench.*`, `*.stories.*`, `*.cy.*`, and anything under `test/`, `tests/` or `__tests__/`), judged from the repository root (every folder above the file up to it), else the topmost folder with a package.json. Restored files are the sender\'s code: read them before you run or import them. Without `--out`, everything comes back into a new folder beside the HTML file, named after it (`page.html` comes back into `page-restored/`). A received file that carries anything else (a file the page never imports, a dotfile, `package.json`, a tool configuration, a path that leaves the folder) is refused with nothing written. A rendered file that lost its embedded source on the way (a sanitizer or an editor strips `<script>` blocks) and has no Astryx components to rebuild from is refused with `ERR_RENDER_SOURCE_DAMAGED`. An existing file is never replaced unless you pass `--overwrite`, and the refusal names every one; a generated, vendored or ignored file, and any path through a symbolic link, is not written even then. Add `--json` for the result as data: what was written, how big it is, and every warning.',
         },
       ],
     },

package/assets/docs/tree/tailwind.doc.mjs

@@ -19,6 +19,8 @@ export const docs = {
     'tailwind-theme.css',
     'utility classes',
     'preflight',
+    'existing Tailwind app',
+    'cascade layer order',
   ],
 
   sections: [
@@ -69,7 +71,45 @@ import {themes, defaultThemeSlug} from './astryx-themes';`,
         },
         {
           type: 'prose',
-          text: 'The Tailwind bridge is the concrete example of the general interop pattern: expose another library\'s semantic API, but point the values at system token variables.',
+          text: "The Tailwind bridge is the concrete example of the general interop pattern: expose another library's semantic API, but point the values at system token variables.",
+        },
+      ],
+    },
+    {
+      title: 'Add Astryx to an app that already uses Tailwind',
+      content: [
+        {
+          type: 'prose',
+          text: 'The recipe in the Tailwind section is a whole `globals.css` for a new app. An app that already uses Tailwind keeps its own file: its `@import "tailwindcss"`, its `@theme` mapping, and its `:root` variables stay as they are. Add one `@layer` line above the Tailwind import and the Astryx stylesheets below it.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'globals.css (existing Tailwind app)',
+          code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
+
+@import "tailwindcss"; /* the app's own entry, unchanged */
+@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
+@import "@astryxdesign/theme-neutral/theme.css";
+
+/* The app's own @theme and :root rules stay below, unchanged. */`,
+        },
+        {
+          type: 'prose',
+          text: "This recipe leaves out `tailwind-theme.css`. The bridge maps Tailwind theme names to system tokens, including Tailwind's own defaults such as `rounded-lg` and `shadow-md`, so in an existing app it changes what the app's own classes paint. Add it only when the app does not use the names it maps.",
+        },
+        {
+          type: 'prose',
+          text: "Astryx's theme defines its own CSS custom properties (color, spacing, radius, shadow, font, motion and more), and {@link namespace:tokens} has the full list. An app token with one of those names collides in one of two ways. An app `@theme` key takes Astryx's value, because `astryx.css` sets the tokens on `:root` above Tailwind's `theme` layer: with `@theme { --spacing-4: 1.5rem }`, the app's `gap-4` stays 16px. Marking the block `@theme inline` keeps the app's value in its utilities. An app `:root` variable replaces Astryx's value, so Astryx's own components change: `:root { --spacing-4: 1.5rem }` widens Astryx's spacing step 4 from 16px to 24px. Where the root Theme component sets a token again, such as `--color-warning`, the app's own rules inside it read Astryx's value instead. Rename any app token that shares a name.",
+        },
+        {
+          type: 'prose',
+          text: "Put the `@layer` line above the app's `@import \"tailwindcss\"`, never below it. A `@layer` statement orders only the layer names the page has not seen yet, and the Tailwind import names `theme`, `base`, `components`, and `utilities` as it loads. Below that import, the statement can only add `reset`, `astryx-base`, and `astryx-theme` after Tailwind's `utilities`. That inverts the cascade: the Astryx reset then outranks every utility class in the app, and, for example, removes the borders and padding the app's utilities give its controls. Nothing reports it: the build and the browser console stay clean, and the `@layer` line still looks right in the source, so only the rendered page shows the problem.",
+        },
+        {
+          type: 'prose',
+          text: 'The load-order rule from the Tailwind section still applies: `globals.css` must be the first stylesheet the page loads, so its `@layer` line names the layers first.',
         },
       ],
     },

package/assets/docs/tree/type-scale.doc.mjs

@@ -2,7 +2,8 @@
 
 /**
  * @file `astryx docs typography/type-scale`: line height, semantic type scale,
- * display text, headings and text components, and custom type scales.
+ * display text, headings and text components, custom type scales, and the
+ * reader's text size on iOS.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -14,13 +15,15 @@ export const docs = {
   placement: {parent: 'namespace:typography', slot: 'guides', order: 20},
   category: 'foundations',
   description:
-    'Line height, semantic type scale tokens, display text, Heading and Text components, and custom type scales via defineTheme.',
+    "Line height, semantic type scale tokens, display text, Heading and Text components, custom type scales via defineTheme, and following the reader's text size on iOS.",
   keywords: [
     'line height',
     'leading',
     'defineTheme',
     'base',
     'ratio',
+    'dynamic type',
+    'text size',
   ],
 
   sections: [
@@ -143,5 +146,19 @@ const denseTheme = defineTheme({
         },
       ],
     },
+    {
+      id: 'dynamic-type',
+      title: "Following the reader's text size on iOS",
+      content: [
+        {
+          type: 'prose',
+          text: "On iPhone, readers pick a text size in Settings (Display & Text Size, then Larger Text), and native apps grow or shrink their text with it. Every theme does the same in Safari on iPhone, which exposes that choice through `font: -apple-system-body`: each font size follows the reader's choice on the curve of the iOS text style it plays, so body text scales like Body, `heading-1` like Title 1 and display text like Large Title, and every role keeps its order. A size the theme fixes at a length, such as a 12px supporting size, scales on the curve of the step it reads by default; a size in `em` or `%` follows its parent, and one that reads a variable follows that variable. At the default size every font size is the theme's own. The family, spacing, radius and the root font size never change, line heights keep their ratios, text inputs keep their 16px floor on iOS, and on Android the system font scale grows every font size through `env(preferred-text-scale)` where the browser reports it; browsers with neither see no change. There is nothing to turn on: no theme option, prop or document attribute.",
+        },
+        {
+          type: 'prose',
+          text: 'Fixed-height controls such as the text inputs keep their height, so their text can overflow at the accessibility sizes. A labelled `Button` grows with its label.',
+        },
+      ],
+    },
   ],
 };

package/assets/templates/blocks/components/Calendar/useCalendarConstraintsHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useCalendarConstraints',
+  name: 'useCalendarConstraints — Hotel Booking Range',
+  displayName: 'useCalendarConstraints — Hotel Booking Range',
+  description:
+    'A hotel booking range picker enforcing season min/max dates, a 7-night maximum stay once check-in is picked, and a custom rule disabling closed Mondays.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Button', 'Layout', 'Text'],
+};

package/assets/templates/blocks/components/Calendar/useCalendarConstraintsHookUsage.tsx

@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {
+  useCalendarConstraints,
+  useCalendarDays,
+  type CalendarDay,
+} from '@astryxdesign/core/Calendar';
+import {Button} from '@astryxdesign/core/Button';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+// Hotel closed on Mondays (day === 1)
+const isNotMonday = (date: Date) => date.getDay() !== 1;
+
+export default function UseCalendarConstraintsHookUsage() {
+  const [checkIn, setCheckIn] = useState<CalendarDay['date'] | null>(null);
+  const [checkOut, setCheckOut] = useState<CalendarDay['date'] | null>(null);
+
+  // June 2026 season: open Jun 5 – Jun 25, max 7 nights (8-day span), closed Mondays.
+  // When checkOut is already chosen, clear rangeAnchor so full season remains viewable without lingering span restrictions.
+  const {isDateDisabled} = useCalendarConstraints({
+    min: '2026-06-05',
+    max: '2026-06-25',
+    maxRangeSpan: 8,
+    rangeAnchor: checkOut ? null : checkIn,
+    dateConstraints: [isNotMonday],
+  });
+
+  const {weeks, dayNames} = useCalendarDays({
+    year: 2026,
+    month: 6,
+    weekStartsOn: 0,
+    hasVariableRowCount: true,
+  });
+
+  const handleSelect = (day: CalendarDay) => {
+    if (day.isOutside || isDateDisabled(day.date)) {
+      return;
+    }
+    // If no check-in yet, or already booked, or clicking on/before current check-in: start new check-in
+    if (!checkIn || checkOut || day.date.day <= checkIn.day) {
+      setCheckIn(day.date);
+      setCheckOut(null);
+    } else {
+      // Pick is after checkIn: set as check-out
+      setCheckOut(day.date);
+    }
+  };
+
+  const handleReset = () => {
+    setCheckIn(null);
+    setCheckOut(null);
+  };
+
+  return (
+    <VStack gap={3}>
+      <VStack gap={1}>
+        <Text type="body" weight="bold">
+          Hotel Booking — June 2026
+        </Text>
+        <Text type="supporting" color="secondary">
+          Season: Jun 5 – Jun 25 · Max stay: 7 nights · Closed Mondays
+        </Text>
+      </VStack>
+      <HStack gap={2} vAlign="center">
+        <Text type="supporting">
+          {checkIn
+            ? checkOut
+              ? `Booked: Jun ${checkIn.day} – Jun ${checkOut.day}`
+              : `Check-in: Jun ${checkIn.day} (pick check-out)`
+            : 'Pick a check-in date'}
+        </Text>
+        {checkIn && (
+          <Button
+            label="Reset"
+            size="sm"
+            variant="secondary"
+            onClick={handleReset}
+          />
+        )}
+      </HStack>
+      <table style={{tableLayout: 'fixed', width: 280}}>
+        <thead>
+          <tr>
+            {dayNames.map((name, i) => (
+              <th key={i} scope="col">
+                <Text type="supporting" color="secondary">
+                  {name}
+                </Text>
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {weeks.map(week => (
+            <tr key={week[0].iso}>
+              {week.map(day => {
+                if (day.isOutside) {
+                  return <td key={day.iso} align="center" />;
+                }
+
+                const disabled = isDateDisabled(day.date);
+                const isSelected =
+                  (checkIn &&
+                    checkIn.day === day.date.day &&
+                    checkIn.month === day.date.month) ||
+                  (checkOut &&
+                    checkOut.day === day.date.day &&
+                    checkOut.month === day.date.month);
+
+                return (
+                  <td key={day.iso} align="center">
+                    <button
+                      type="button"
+                      disabled={disabled}
+                      onClick={() => handleSelect(day)}
+                      aria-pressed={isSelected ? 'true' : 'false'}
+                      aria-label={`June ${day.dayNumber}`}
+                      style={{
+                        width: 32,
+                        height: 32,
+                        borderRadius: 6,
+                        border: isSelected ? '1px solid currentColor' : 'none',
+                        background: 'transparent',
+                        opacity: disabled ? 0.35 : 1,
+                        cursor: disabled ? 'not-allowed' : 'pointer',
+                      }}>
+                      <Text
+                        type="body"
+                        color={disabled ? 'secondary' : 'primary'}>
+                        {day.dayNumber}
+                      </Text>
+                    </button>
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </VStack>
+  );
+}

package/assets/templates/blocks/components/Calendar/useCalendarNavigationHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useCalendarNavigation',
+  name: 'useCalendarNavigation — Month Pager',
+  displayName: 'useCalendarNavigation — Month Pager',
+  description:
+    'A calendar month pager with previous/next navigation buttons, localized month-year label, and cross-month arrow key navigation using pendingFocus.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Button', 'Layout', 'Text'],
+};

package/assets/templates/blocks/components/Calendar/useCalendarNavigationHookUsage.tsx

@@ -0,0 +1,173 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useEffect, useRef, useState} from 'react';
+import {
+  useCalendarDays,
+  useCalendarNavigation,
+  type CalendarDay,
+  type ISODateString,
+} from '@astryxdesign/core/Calendar';
+import {Button} from '@astryxdesign/core/Button';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function UseCalendarNavigationHookUsage() {
+  const [focusDate, setFocusDate] = useState<ISODateString>(
+    '2026-06-01' as ISODateString,
+  );
+
+  const {
+    monthYearLabel,
+    visibleCalendarMonths,
+    navigateMonth,
+    pendingFocus,
+    clearPendingFocus,
+  } = useCalendarNavigation({
+    focusDate,
+    onFocusDateChange: setFocusDate,
+    numberOfMonths: 1,
+  });
+
+  const {weeks, dayNames} = useCalendarDays({
+    ...visibleCalendarMonths[0],
+    weekStartsOn: 0,
+    hasVariableRowCount: true,
+  });
+
+  const dayButtonRefs = useRef<Map<string, HTMLButtonElement>>(new Map());
+
+  // Move focus to target date when navigating across month boundaries
+  useEffect(() => {
+    if (pendingFocus) {
+      const el = dayButtonRefs.current.get(pendingFocus);
+      if (el) {
+        el.focus();
+        clearPendingFocus();
+      }
+    }
+  }, [pendingFocus, clearPendingFocus, weeks]);
+
+  // Arrow key navigation moving across days and month boundaries with RTL awareness (DR6, DR11)
+  const handleKeyDown = (
+    e: React.KeyboardEvent<HTMLButtonElement>,
+    day: CalendarDay,
+  ) => {
+    if (day.isOutside) {
+      return;
+    }
+
+    const isRtl =
+      typeof window !== 'undefined' &&
+      getComputedStyle(e.currentTarget).direction === 'rtl';
+
+    const isNext = isRtl ? e.key === 'ArrowLeft' : e.key === 'ArrowRight';
+    const isPrev = isRtl ? e.key === 'ArrowRight' : e.key === 'ArrowLeft';
+
+    if (isNext) {
+      e.preventDefault();
+      const inMonthDays = weeks.flatMap(w => w.filter(d => !d.isOutside));
+      const currentIndex = inMonthDays.findIndex(d => d.iso === day.iso);
+      if (currentIndex === inMonthDays.length - 1) {
+        // Last day of month: advance month and focus next day across boundary
+        navigateMonth(1, day.iso, 1);
+      } else {
+        const nextDay = inMonthDays[currentIndex + 1];
+        dayButtonRefs.current.get(nextDay.iso)?.focus();
+      }
+    } else if (isPrev) {
+      e.preventDefault();
+      const inMonthDays = weeks.flatMap(w => w.filter(d => !d.isOutside));
+      const currentIndex = inMonthDays.findIndex(d => d.iso === day.iso);
+      if (currentIndex === 0) {
+        // First day of month: step back month and focus previous day across boundary
+        navigateMonth(-1, day.iso, 1);
+      } else {
+        const prevDay = inMonthDays[currentIndex - 1];
+        dayButtonRefs.current.get(prevDay.iso)?.focus();
+      }
+    }
+  };
+
+  return (
+    <VStack gap={3} style={{width: 280}}>
+      <HStack gap={2} vAlign="center" hAlign="between">
+        <Button
+          label="Previous"
+          size="sm"
+          variant="secondary"
+          onClick={() => navigateMonth(-1)}
+          aria-label="Previous month"
+        />
+        <Text type="body" weight="bold">
+          {monthYearLabel}
+        </Text>
+        <Button
+          label="Next"
+          size="sm"
+          variant="secondary"
+          onClick={() => navigateMonth(1)}
+          aria-label="Next month"
+        />
+      </HStack>
+
+      <table style={{tableLayout: 'fixed', width: 280}}>
+        <thead>
+          <tr>
+            {dayNames.map((name, i) => (
+              <th key={i} scope="col">
+                <Text type="supporting" color="secondary">
+                  {name}
+                </Text>
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {weeks.map(week => (
+            <tr key={week[0].iso}>
+              {week.map(day => (
+                <td key={day.iso} align="center">
+                  <button
+                    type="button"
+                    ref={el => {
+                      if (el) {
+                        dayButtonRefs.current.set(day.iso, el);
+                      } else {
+                        dayButtonRefs.current.delete(day.iso);
+                      }
+                    }}
+                    disabled={day.isOutside}
+                    aria-hidden={day.isOutside || undefined}
+                    onKeyDown={e => handleKeyDown(e, day)}
+                    aria-label={
+                      day.isOutside
+                        ? undefined
+                        : `${monthYearLabel} ${day.dayNumber}`
+                    }
+                    tabIndex={day.isOutside ? -1 : 0}
+                    style={{
+                      width: 32,
+                      height: 32,
+                      borderRadius: 6,
+                      border: 'none',
+                      background: 'transparent',
+                      opacity: day.isOutside ? 0.35 : 1,
+                      cursor: day.isOutside ? 'not-allowed' : 'pointer',
+                    }}>
+                    <Text
+                      type="body"
+                      color={day.isOutside ? 'secondary' : 'primary'}>
+                      {day.dayNumber}
+                    </Text>
+                  </button>
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </VStack>
+  );
+}

package/assets/templates/blocks/components/Hooks/useInputStatusIconHookUsage.tsx

@@ -74,6 +74,7 @@ function CouponField({statusVariant}: {statusVariant: FieldStatusPlacement}) {
       <div
         {...stylex.props(
           inputWrapperStyles.base,
+          inputWrapperStyles.textField,
           styles.field,
           status && inputStatusBorderStyles[status.type],
         )}>

package/assets/templates/blocks/components/Hooks/useInteractiveRoleHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useInteractiveRole',
+  name: 'useInteractiveRole — One Tile, Four Roles',
+  displayName: 'useInteractiveRole — One Tile, Four Roles',
+  description:
+    'A polymorphic Tile used four ways: with an href it renders as a link, with an onClick as a button, with neither as plain content, and placed as a Popover trigger it becomes the trigger button through context — the resolution order in one place.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Popover', 'Card', 'Text', 'Layout', 'Link'],
+};

package/assets/templates/blocks/components/Hooks/useInteractiveRoleHookUsage.tsx

@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useInteractiveRole} from '@astryxdesign/core/hooks';
+import {Link} from '@astryxdesign/core/Link';
+import {Popover} from '@astryxdesign/core/Popover';
+import {Card} from '@astryxdesign/core/Card';
+import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
+
+// A polymorphic Tile: the hook alone decides what it renders as — href wins,
+// then onClick, then a trigger context (Popover), then inert.
+function Tile({
+  href,
+  onClick,
+  children,
+}: {
+  href?: string;
+  onClick?: () => void;
+  children: React.ReactNode;
+}) {
+  const role = useInteractiveRole({href, onClick});
+  const body = (
+    <Card padding={3} width={200}>
+      <Text type="body">{children}</Text>
+    </Card>
+  );
+  switch (role) {
+    case 'link':
+      return <Link href={href}>{body}</Link>;
+    case 'button':
+      return <button onClick={onClick}>{body}</button>;
+    default:
+      return body;
+  }
+}
+
+export default function UseInteractiveRoleHookUsage() {
+  return (
+    <VStack gap={3} hAlign="center" style={{width: '100%'}}>
+      <Tile href="https://example.com/docs">Renders as a link</Tile>
+      <Tile onClick={() => {}}>Renders as a button</Tile>
+      <Popover
+        label="Tile details"
+        content={
+          <Card padding={3}>
+            <Text type="body">Opened through the tile's context role</Text>
+          </Card>
+        }>
+        <Tile>Trigger via context</Tile>
+      </Popover>
+      <Tile>Plain content</Tile>
+    </VStack>
+  );
+}

package/assets/templates/blocks/components/Hooks/useStreamingTextHookUsage.doc.mjs

@@ -7,8 +7,8 @@ export const doc = {
   name: 'useStreamingText — Streaming Response',
   displayName: 'useStreamingText — Streaming Response',
   description:
-    'Smooth bursty generated text into a steady reveal with useStreamingText.',
+    'A chat-style reply card: while the response streams in bursts, useStreamingText reveals it steadily character by character; when streaming ends the full text snaps into place. Regenerate replays the stream.',
   isReady: true,
   aspectRatio: 4 / 3,
-  componentsUsed: ['Card', 'Text', 'Layout'],
+  componentsUsed: ['Button', 'Card', 'Text', 'Layout'],
 };