@astryxdesign/core 0.4.3 → 0.4.4-canary.0f4d45f

package/src/BottomSheet/BottomSheetSwitcher.doc.mjs

@@ -0,0 +1,219 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'BottomSheetSwitcher',
+  displayName: 'Bottom Sheet Switcher',
+  group: 'BottomSheet',
+  category: 'Overlay',
+  keywords: ['bottom sheet', 'switcher', 'multi-step', 'flow', 'wizard'],
+  playground: {
+    overlay: true,
+    overlayControl: {
+      stateProp: 'activeSheet',
+      openValue: 'details',
+    },
+    defaults: {
+      activeSheet: null,
+      children: [
+        {
+          __element: 'BottomSheet',
+          props: {
+            sheetId: 'details',
+            label: 'Setup details',
+            height: 'hug',
+          },
+          children: {
+            __element: 'Section',
+            props: {padding: 4},
+            children: {
+              __element: 'VStack',
+              props: {gap: 2},
+              children: [
+                {
+                  __element: 'Heading',
+                  props: {level: 3},
+                  children: 'Setup details',
+                },
+                {
+                  __element: 'Text',
+                  props: {type: 'body'},
+                  children: 'Add the essential information for this setup.',
+                },
+                {
+                  __element: 'Text',
+                  props: {type: 'supporting'},
+                  children: 'You can review these details before saving.',
+                },
+              ],
+            },
+          },
+        },
+        {
+          __element: 'BottomSheet',
+          props: {
+            sheetId: 'preferences',
+            label: 'Choose preferences',
+            height: 'hug',
+          },
+          children: {
+            __element: 'Section',
+            props: {padding: 4},
+            children: {
+              __element: 'VStack',
+              props: {gap: 2},
+              children: [
+                {
+                  __element: 'Heading',
+                  props: {level: 3},
+                  children: 'Choose preferences',
+                },
+                {
+                  __element: 'Text',
+                  props: {type: 'body'},
+                  children: 'Select how this setup should behave.',
+                },
+                {
+                  __element: 'Text',
+                  props: {type: 'supporting'},
+                  children:
+                    'Notifications can be sent immediately, daily, or weekly.',
+                },
+                {
+                  __element: 'Text',
+                  props: {type: 'supporting'},
+                  children: 'You can update these preferences later.',
+                },
+              ],
+            },
+          },
+        },
+        {
+          __element: 'BottomSheet',
+          props: {
+            sheetId: 'confirm',
+            label: 'Confirm setup',
+            height: 'hug',
+          },
+          children: {
+            __element: 'Section',
+            props: {padding: 4},
+            children: {
+              __element: 'VStack',
+              props: {gap: 2},
+              children: [
+                {
+                  __element: 'Heading',
+                  props: {level: 3},
+                  children: 'Confirm setup',
+                },
+                {
+                  __element: 'Text',
+                  props: {type: 'body'},
+                  children: 'Everything is ready to save.',
+                },
+              ],
+            },
+          },
+        },
+      ],
+    },
+  },
+  description:
+    'Coordinates multiple BottomSheets as a mutually exclusive flow. One activeSheet ID selects the only interactive sheet; during a handoff, the new sheet enters above the inert previous sheet. If the new sheet is shorter, the previous sheet simultaneously moves down until their top edges align, then fades after both transforms complete. The switcher owns one shared native <dialog>: modal flows call showModal() once for one top-layer boundary and one ::backdrop across the whole flow, while no-scrim flows use a non-modal show() shell. Its ref and shared DOM props target that dialog.',
+  props: [
+    {
+      name: 'activeSheet',
+      type: 'string | null',
+      description:
+        "ID of the interactive BottomSheet, or null when the flow should close. Match a nested BottomSheet's unique sheetId; the previous sheet may remain visually present and inert while the new sheet enters, simultaneously align downward behind a shorter step, then fade away.",
+      required: true,
+    },
+    {
+      name: 'onActiveSheetChange',
+      type: '(activeSheet: string | null) => void',
+      description:
+        "Called with null when the active sheet dismisses according to its purpose. Child BottomSheets may use purpose='form' or purpose='required' to limit implicit dismissal while flow controls can still use the same state setter to switch sheets or close the flow.",
+      required: true,
+    },
+    {
+      name: 'hasScrim',
+      type: 'boolean',
+      description:
+        "Whether the shared dialog is modal. true uses showModal() once for one native ::backdrop, focus trap, scroll lock, and click-to-dismiss when the active BottomSheet has purpose='info'. false uses show() with no backdrop and leaves the page interactive; avoid transformed, contained, or clipping ancestors because the non-modal dialog remains in its containing context.",
+      default: 'true',
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'BottomSheets identified by unique sheetId values.',
+      required: true,
+    },
+  ],
+  usage: {
+    description:
+      "Coordinates a multi-step bottom-sheet flow in one shared dialog; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use when each step depends on the previous one and only one step needs attention at a time.',
+      },
+      {
+        guidance: false,
+        description:
+          "Don't split information across sheets when people need to compare it; use a full-page layout that keeps the relevant content visible together instead.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: 'Three-step flow',
+      code: `const [activeSheet, setActiveSheet] = useState(null);
+
+<>
+  <Button label="Start" onClick={() => setActiveSheet('details')} />
+  <BottomSheetSwitcher
+    activeSheet={activeSheet}
+    onActiveSheetChange={setActiveSheet}>
+    <BottomSheet sheetId="details" label="Details" height="hug">
+      <SetupDetails />
+      <Button label="Continue" onClick={() => setActiveSheet('preferences')} />
+    </BottomSheet>
+    <BottomSheet sheetId="preferences" label="Preferences" height="hug">
+      <Preferences />
+      <Button label="Back" onClick={() => setActiveSheet('details')} />
+      <Button label="Continue" onClick={() => setActiveSheet('confirm')} />
+    </BottomSheet>
+    <BottomSheet sheetId="confirm" label="Confirm" height="hug">
+      <Confirmation />
+      <Button label="Back" onClick={() => setActiveSheet('preferences')} />
+      <Button label="Done" onClick={() => setActiveSheet(null)} />
+    </BottomSheet>
+  </BottomSheetSwitcher>
+</>`,
+    },
+  ],
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+  description:
+    'controller with one shared native dialog for mutually exclusive multi-step BottomSheets',
+  usage: {
+    description:
+      "Coordinates a multi-step bottom-sheet flow in one shared dialog; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use when each step depends on the previous one and only one step needs attention at a time.',
+      },
+      {
+        guidance: false,
+        description:
+          "Don't split information across sheets when people need to compare it; use a full-page layout that keeps the relevant content visible together instead.",
+      },
+    ],
+  },
+};