@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/fullscreen.json

@@ -0,0 +1,414 @@
+{
+  "family": "fullscreen",
+  "ui": "fullscreen",
+  "binding": "react",
+  "catalog": {
+    "group": "Actions",
+    "summary": "Enters and leaves fullscreen for an element."
+  },
+  "axes": {
+    "mode": [
+      "auto",
+      "layout"
+    ],
+    "navigationUI": [
+      "auto",
+      "show",
+      "hide"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "ghost",
+      "outline"
+    ]
+  },
+  "members": {
+    "fullscreen": {
+      "nativeElement": "div",
+      "defaults": {
+        "mode": "auto",
+        "navigationUI": "auto",
+        "defaultFullscreen": false,
+        "size": "md",
+        "variant": "ghost",
+        "iconOnly": false,
+        "type": "button",
+        "disabled": false
+      },
+      "capabilities": [
+        "fullscreen",
+        "size",
+        "appearance",
+        "content",
+        "disabled",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "fullscreen",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "trigger",
+        "content",
+        "icon",
+        "label"
+      ]
+    }
+  },
+  "docs": {
+    "fullscreen": {
+      "imports": {
+        "source": "import { Fullscreen, FullscreenContent, FullscreenTrigger, FullscreenDefaultsProvider, useFullscreen } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The region that goes full screen. At rest it paints nothing — it is the container the consumer already had. In full screen it carries data-fullscreen and data-mode (native or layout), takes the page ground and the inset, and scrolls by itself."
+        },
+        {
+          "part": "trigger",
+          "element": "button, or the element render returns",
+          "required": false,
+          "purpose": "The control. It carries data-ui=\"fullscreen\" of its own, so it is styled wherever it stands — inside the region, or in a toolbar outside it with target. Its words and its mark say what the press does next."
+        },
+        {
+          "part": "content",
+          "element": "div, or the element render returns",
+          "required": false,
+          "purpose": "A direct child of the region that takes, in full screen, the height the other children leave; its first child fills it. Without it, a region with one child gives that child the height, and a lone img, video or canvas fills it with object-fit: contain."
+        },
+        {
+          "part": "icon",
+          "element": "span",
+          "required": true,
+          "purpose": "The mark, hidden from the reading order. Empty, it draws the four corners opening (maximize) or closing (minimize) from the glyph tokens; a consumer icon placed in it replaces the mark."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "The words — “Full screen” or “Exit full screen” from the catalog of the language in force, or the consumer’s. With iconOnly they are visually hidden and stay the accessible name."
+        }
+      ],
+      "api": [
+        {
+          "name": "fullscreen",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Fullscreen",
+          "description": "Present means the consumer owns the state for the life of the component. Absent, the region owns it and starts from defaultFullscreen"
+        },
+        {
+          "name": "defaultFullscreen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Fullscreen",
+          "description": "What an uncontrolled region starts from, read once. True on mount asks the browser outside a gesture, which refuses, so the region starts in the layout"
+        },
+        {
+          "name": "mode",
+          "type": "'auto' | 'layout'",
+          "defaultValue": "auto",
+          "appliesTo": "Fullscreen",
+          "description": "auto asks the browser and falls back to the layout when it has no API or refuses; layout never asks"
+        },
+        {
+          "name": "navigationUI",
+          "type": "'auto' | 'show' | 'hide'",
+          "defaultValue": "auto",
+          "appliesTo": "Fullscreen",
+          "description": "Passed to the native request: whether the browser keeps its navigation interface on screen"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<FullscreenMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Fullscreen",
+          "description": "Words laid over the language in force, key by key: the two labels of the control (enter, exit) and the two announcements (entered, exited). entered says how to leave"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "FullscreenTrigger",
+          "description": "The control step, from the control scale"
+        },
+        {
+          "name": "variant",
+          "type": "'ghost' | 'outline'",
+          "defaultValue": "ghost",
+          "appliesTo": "FullscreenTrigger",
+          "description": "ghost inside a framed bar; outline over content, with its own ground"
+        },
+        {
+          "name": "iconOnly",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "FullscreenTrigger",
+          "description": "The mark alone in a square; the words stay as the accessible name"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode | (fullscreen: boolean) => ReactNode",
+          "defaultValue": "the message",
+          "appliesTo": "FullscreenTrigger",
+          "description": "Words in place of the message the state picks"
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode | (fullscreen: boolean) => ReactNode",
+          "defaultValue": "maximize / minimize",
+          "appliesTo": "FullscreenTrigger",
+          "description": "A mark in place of the family’s"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "FullscreenTrigger",
+          "description": "The native attribute; the press is refused"
+        },
+        {
+          "name": "type",
+          "type": "'button' | 'submit' | 'reset'",
+          "defaultValue": "button",
+          "appliesTo": "FullscreenTrigger",
+          "description": "The native type; a button unless the consumer says otherwise"
+        },
+        {
+          "name": "target",
+          "type": "FullscreenHandle",
+          "defaultValue": "the nearest Fullscreen",
+          "appliesTo": "FullscreenTrigger",
+          "description": "The handle of a region the control is not inside"
+        }
+      ],
+      "composition": [
+        {
+          "name": "useFullscreen",
+          "type": "(target, options) => FullscreenHandle",
+          "defaultValue": "—",
+          "appliesTo": "any element",
+          "description": "The state and the actions for any element: { fullscreen, mode, supported, error, enter, exit, toggle }"
+        },
+        {
+          "name": "FullscreenDefaultsProvider",
+          "type": "{ mode, navigationUI, size, variant }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once; an instance still wins"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Fullscreen, FullscreenTrigger",
+          "description": "Substitutes the element and hands it every attribute and the ref callback the family was going to write"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement> / Ref<HTMLButtonElement>",
+          "defaultValue": "—",
+          "appliesTo": "Fullscreen, FullscreenTrigger",
+          "description": "The native elements"
+        },
+        {
+          "name": "FullscreenContent",
+          "type": "ComponentPropsWithRef<'div'> & { render? }",
+          "defaultValue": "—",
+          "appliesTo": "a direct child of Fullscreen",
+          "description": "The part that takes the height in full screen; render substitutes its element"
+        },
+        {
+          "name": "useFullscreenContext",
+          "type": "() => FullscreenHandle | null",
+          "defaultValue": "—",
+          "appliesTo": "inside Fullscreen",
+          "description": "The handle for a consumer control of its own"
+        }
+      ],
+      "events": [
+        {
+          "name": "onFullscreenChange",
+          "payload": "(fullscreen: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before the state moves. The reason is pointer or keyboard from the control, programmatic from the handle, and escape when the reader left on their own — Escape in the layout, or the browser’s own exit in native, which has already happened by then. cancel() refuses it."
+        },
+        {
+          "name": "onFullscreenError",
+          "payload": "({ kind: 'unsupported' | 'refused', cause?: unknown })",
+          "when": "When the browser has no API or refuses the request. The region has already entered the layout and the state stays true."
+        },
+        {
+          "name": "onClick",
+          "payload": "the button’s own event",
+          "when": "On the control, before the family acts. preventDefault() refuses the press."
+        }
+      ],
+      "accessibility": [
+        "The control is a native button whose label says what the press does next, so it carries no aria-pressed: the APG Button pattern (w3.org/WAI/ARIA/apg/patterns/button/) keeps aria-pressed for a toggle whose label does not change. A screen reader hears “Full screen, button” and then “Exit full screen, button”.",
+        "Escape in native full screen belongs to the browser, and the family writes no listener for it; the specification makes it leave before any close watcher. In the layout, Escape asks through the one layer stack, so a list opened inside closes first.",
+        "While the region is full screen, Tab wraps inside it: what is outside is not painted, and a focus there would be invisible. On the way out, focus returns to the element that held it when it came from outside, and the page’s and the region’s scroll return to where they were.",
+        "Entering is announced politely with how to leave (“Full screen. Press Escape to exit.”), and leaving is announced too; the layout does not make the page inert, because an inert page would silence that announcement. The cost is that a screen reader’s virtual cursor can reach the covered page."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-font-weight",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-letter-spacing",
+    "--slotted-control-line-height",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-surface",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-instant",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-fullscreen-inset",
+    "--slotted-fullscreen-surface",
+    "--slotted-fullscreen-trigger-active-background",
+    "--slotted-fullscreen-trigger-border-color",
+    "--slotted-fullscreen-trigger-color",
+    "--slotted-fullscreen-trigger-hover-background",
+    "--slotted-fullscreen-trigger-radius",
+    "--slotted-space-5",
+    "--slotted-space-8",
+    "--slotted-surface",
+    "--slotted-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-z-index-overlay"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "A revenue panel with its control in the header. Press it: the panel takes the screen through the browser, the words become “Exit full screen” and the mark turns inward. Escape, or the control again, gives the page back with the scroll where it was.",
+      "language": "tsx",
+      "source": "<Fullscreen>\n  <FullscreenContent>\n    <Chart actions={<FullscreenTrigger iconOnly />} title=\"Receita por mês\" {...revenue} />\n  </FullscreenContent>\n</Fullscreen>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "layout",
+      "title": "Inside the page, where the browser will not",
+      "note": "mode=\"layout\" never asks the browser: the region is fixed over the page, the page behind stops scrolling, and Escape leaves. It is the picture an iframe without allow=\"fullscreen\" or a phone browser gets under the default mode too.",
+      "language": "tsx",
+      "source": "<Fullscreen mode=\"layout\">\n  <FullscreenTrigger />\n  <ContractTerms />\n</Fullscreen>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "fill",
+      "title": "The height of the screen, not only its width",
+      "note": "The browser stretches the region and none of its children. FullscreenContent takes the height a bar and a caption leave, and the chart’s plot grows into it; a region with a single card gives the card the height instead.",
+      "language": "tsx",
+      "source": "<Fullscreen>\n  <Toolbar>\n    <FullscreenTrigger />\n  </Toolbar>\n  <FullscreenContent>\n    <Chart title=\"Receita por mês\" {...revenue} />\n  </FullscreenContent>\n  <Text>Fonte: fechamento contábil.</Text>\n</Fullscreen>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "controlled",
+      "title": "The page holds the state",
+      "note": "The page owns fullscreen and every change arrives as a request with its reason: pointer or keyboard from the control, escape when the reader left on their own. The log under the panel prints each one.",
+      "language": "tsx",
+      "source": "const [presenting, setPresenting] = useState(false);\n\n<Fullscreen\n  fullscreen={presenting}\n  onFullscreenChange={(next, request) => {\n    log(request.reason);\n    setPresenting(next);\n  }}\n>\n  <FullscreenTrigger />\n</Fullscreen>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "error",
+      "title": "Refused, and still full screen",
+      "note": "When the browser has no API or refuses, the region enters the layout and onFullscreenError says why — unsupported or refused. The panel prints the last error. A page that prefers nothing sets the state back to false from the same handler.",
+      "language": "tsx",
+      "source": "<Fullscreen onFullscreenError={(error) => setNotice(error.kind)}>\n  <FullscreenTrigger />\n</Fullscreen>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "overlays",
+      "title": "A menu opened from inside",
+      "note": "The select in the panel opens its list inside the region while it is full screen: the portal root follows the element the browser shows. Escape in the layout closes the list first and the region on the second press.",
+      "language": "tsx",
+      "source": "<Fullscreen>\n  <Select defaultValue=\"6m\">\n    <SelectTrigger aria-label=\"Período\">\n      <SelectValue />\n    </SelectTrigger>\n    <SelectContent>\n      <SelectItem value=\"3m\">Últimos 3 meses</SelectItem>\n      <SelectItem value=\"6m\">Últimos 6 meses</SelectItem>\n    </SelectContent>\n  </Select>\n  <FullscreenTrigger />\n</Fullscreen>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "document",
+      "title": "The whole document",
+      "note": "useFullscreen takes any element — here document.documentElement — and hands its handle to a control that is not inside any region. Presentation mode for the whole application is this line and nothing else.",
+      "language": "tsx",
+      "source": "const page = useFullscreen(document.documentElement);\n\n<FullscreenTrigger target={page} variant=\"outline\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard, key by key",
+      "note": "Tab reaches the control, Space or Enter presses it and the reason says keyboard. While full screen, Tab wraps inside the region. Escape in native full screen belongs to the browser — the family writes no listener and reports the leave as escape.",
+      "language": "tsx",
+      "source": "<Fullscreen onFullscreenChange={(next, request) => log(request.reason)}>\n  <FullscreenTrigger />\n</Fullscreen>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "trigger",
+      "title": "The control: two variants, three steps, every state",
+      "note": "ghost stands in a bar that is already framed, outline over content and carries its own ground. Each step reads the control scale, so the control lines up with a button of the same step. Disabled keeps the words legible and refuses the press.",
+      "language": "tsx",
+      "source": "<FullscreenTrigger size=\"sm\" variant=\"outline\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "iconOnly",
+      "title": "The mark alone",
+      "note": "iconOnly draws the control square from its height and keeps the words, visually hidden, as its name — so it still says “Exit full screen” to a screen reader when the mark turns inward.",
+      "language": "tsx",
+      "source": "<FullscreenTrigger iconOnly />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "outside",
+      "title": "The control outside the region",
+      "note": "A toolbar above a chart holds the control; the chart is the region. useFullscreen gives the handle, target hands it to the control, and the control changes with the chart’s state. Inside the region, a second control takes the reader back.",
+      "language": "tsx",
+      "source": "const [chart, setChart] = useState<HTMLElement | null>(null);\nconst handle = useFullscreen(chart);\n\n<>\n  <FullscreenTrigger target={handle} />\n  <section ref={setChart}>…</section>\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Defaults once, words and mark of the consumer",
+      "note": "A provider sets the control’s step and variant for a subtree. children and icon take a function of the state, so a “Present” control keeps following it; render puts the wiring on the consumer’s own element.",
+      "language": "tsx",
+      "source": "<FullscreenDefaultsProvider size=\"sm\">\n  <Fullscreen>\n    <FullscreenTrigger icon={(on) => (on ? <X size={14} /> : <Presentation size={14} />)}>\n      {(on) => (on ? 'Terminar' : 'Apresentar')}\n    </FullscreenTrigger>\n  </Fullscreen>\n</FullscreenDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/fullscreen.md

@@ -0,0 +1,246 @@
+<!-- index: ./index.md -->
+# fullscreen
+
+`data-ui="fullscreen"` · Enters and leaves fullscreen for an element.
+
+## Import
+
+```tsx
+import { Fullscreen, FullscreenContent, FullscreenTrigger, FullscreenDefaultsProvider, useFullscreen } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Fullscreen>
+  <FullscreenContent>
+    <Chart actions={<FullscreenTrigger iconOnly />} title="Receita por mês" {...revenue} />
+  </FullscreenContent>
+</Fullscreen>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `trigger` | button, or the element render returns | no |
+| `content` | div, or the element render returns | no |
+| `icon` | span | yes |
+| `label` | span | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `fullscreen` | `boolean` | — | Fullscreen | Present means the consumer owns the state for the life of the component. Absent, the region owns it and starts from defaultFullscreen |
+| `defaultFullscreen` | `boolean` | false | Fullscreen | What an uncontrolled region starts from, read once. True on mount asks the browser outside a gesture, which refuses, so the region starts in the layout |
+| `mode` | `'auto' \| 'layout'` | auto | Fullscreen | auto asks the browser and falls back to the layout when it has no API or refuses; layout never asks |
+| `navigationUI` | `'auto' \| 'show' \| 'hide'` | auto | Fullscreen | Passed to the native request: whether the browser keeps its navigation interface on screen |
+| `messages` | `Partial<FullscreenMessages>` | — | Fullscreen | Words laid over the language in force, key by key: the two labels of the control (enter, exit) and the two announcements (entered, exited). entered says how to leave |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | FullscreenTrigger | The control step, from the control scale |
+| `variant` | `'ghost' \| 'outline'` | ghost | FullscreenTrigger | ghost inside a framed bar; outline over content, with its own ground |
+| `iconOnly` | `boolean` | false | FullscreenTrigger | The mark alone in a square; the words stay as the accessible name |
+| `children` | `ReactNode \| (fullscreen: boolean) => ReactNode` | the message | FullscreenTrigger | Words in place of the message the state picks |
+| `icon` | `ReactNode \| (fullscreen: boolean) => ReactNode` | maximize / minimize | FullscreenTrigger | A mark in place of the family’s |
+| `disabled` | `boolean` | false | FullscreenTrigger | The native attribute; the press is refused |
+| `type` | `'button' \| 'submit' \| 'reset'` | button | FullscreenTrigger | The native type; a button unless the consumer says otherwise |
+| `target` | `FullscreenHandle` | the nearest Fullscreen | FullscreenTrigger | The handle of a region the control is not inside |
+| `useFullscreen` | `(target, options) => FullscreenHandle` | — | any element | The state and the actions for any element: { fullscreen, mode, supported, error, enter, exit, toggle } |
+| `FullscreenDefaultsProvider` | `{ mode, navigationUI, size, variant }` | — | a subtree | The decisions an application takes once; an instance still wins |
+| `render` | `(props) => ReactNode` | — | Fullscreen, FullscreenTrigger | Substitutes the element and hands it every attribute and the ref callback the family was going to write |
+| `ref` | `Ref<HTMLDivElement> / Ref<HTMLButtonElement>` | — | Fullscreen, FullscreenTrigger | The native elements |
+| `FullscreenContent` | `ComponentPropsWithRef<'div'> & { render? }` | — | a direct child of Fullscreen | The part that takes the height in full screen; render substitutes its element |
+| `useFullscreenContext` | `() => FullscreenHandle \| null` | — | inside Fullscreen | The handle for a consumer control of its own |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onFullscreenChange` | `(fullscreen: boolean, request: ChangeRequest<boolean>)` | Before the state moves. The reason is pointer or keyboard from the control, programmatic from the handle, and escape when the reader left on their own — Escape in the layout, or the browser’s own exit in native, which has already happened by then. cancel() refuses it. |
+| `onFullscreenError` | `({ kind: 'unsupported' \| 'refused', cause?: unknown })` | When the browser has no API or refuses the request. The region has already entered the layout and the state stays true. |
+| `onClick` | `the button’s own event` | On the control, before the family acts. preventDefault() refuses the press. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `mode` | `auto`, `layout` | `auto` |
+| `navigationUI` | `auto`, `show`, `hide` | `auto` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `ghost`, `outline` | `ghost` |
+
+## Rules
+
+- The control is a native button whose label says what the press does next, so it carries no aria-pressed: the APG Button pattern (w3.org/WAI/ARIA/apg/patterns/button/) keeps aria-pressed for a toggle whose label does not change. A screen reader hears “Full screen, button” and then “Exit full screen, button”.
+- Escape in native full screen belongs to the browser, and the family writes no listener for it; the specification makes it leave before any close watcher. In the layout, Escape asks through the one layer stack, so a list opened inside closes first.
+- While the region is full screen, Tab wraps inside it: what is outside is not painted, and a focus there would be invisible. On the way out, focus returns to the element that held it when it came from outside, and the page’s and the region’s scroll return to where they were.
+- Entering is announced politely with how to leave (“Full screen. Press Escape to exit.”), and leaving is announced too; the layout does not make the page inert, because an inert page would silence that announcement. The cost is that a screen reader’s virtual cursor can reach the covered page.
+
+## Tokens
+
+`--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-font-weight`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-letter-spacing`, `--slotted-control-line-height`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-fullscreen-inset`, `--slotted-fullscreen-surface`, `--slotted-fullscreen-trigger-active-background`, `--slotted-fullscreen-trigger-border-color`, `--slotted-fullscreen-trigger-color`, `--slotted-fullscreen-trigger-hover-background`, `--slotted-fullscreen-trigger-radius`, `--slotted-space-5`, `--slotted-space-8`, `--slotted-surface`, `--slotted-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-overlay`
+
+## Examples
+
+### Inside the page, where the browser will not
+
+mode="layout" never asks the browser: the region is fixed over the page, the page behind stops scrolling, and Escape leaves. It is the picture an iframe without allow="fullscreen" or a phone browser gets under the default mode too.
+
+Excerpt — not a complete module
+
+```tsx
+<Fullscreen mode="layout">
+  <FullscreenTrigger />
+  <ContractTerms />
+</Fullscreen>;
+```
+
+### The height of the screen, not only its width
+
+The browser stretches the region and none of its children. FullscreenContent takes the height a bar and a caption leave, and the chart’s plot grows into it; a region with a single card gives the card the height instead.
+
+Excerpt — not a complete module
+
+```tsx
+<Fullscreen>
+  <Toolbar>
+    <FullscreenTrigger />
+  </Toolbar>
+  <FullscreenContent>
+    <Chart title="Receita por mês" {...revenue} />
+  </FullscreenContent>
+  <Text>Fonte: fechamento contábil.</Text>
+</Fullscreen>;
+```
+
+### The page holds the state
+
+The page owns fullscreen and every change arrives as a request with its reason: pointer or keyboard from the control, escape when the reader left on their own. The log under the panel prints each one.
+
+Excerpt — not a complete module
+
+```tsx
+const [presenting, setPresenting] = useState(false);
+
+<Fullscreen
+  fullscreen={presenting}
+  onFullscreenChange={(next, request) => {
+    log(request.reason);
+    setPresenting(next);
+  }}
+>
+  <FullscreenTrigger />
+</Fullscreen>;
+```
+
+### Refused, and still full screen
+
+When the browser has no API or refuses, the region enters the layout and onFullscreenError says why — unsupported or refused. The panel prints the last error. A page that prefers nothing sets the state back to false from the same handler.
+
+Excerpt — not a complete module
+
+```tsx
+<Fullscreen onFullscreenError={(error) => setNotice(error.kind)}>
+  <FullscreenTrigger />
+</Fullscreen>;
+```
+
+### A menu opened from inside
+
+The select in the panel opens its list inside the region while it is full screen: the portal root follows the element the browser shows. Escape in the layout closes the list first and the region on the second press.
+
+Excerpt — not a complete module
+
+```tsx
+<Fullscreen>
+  <Select defaultValue="6m">
+    <SelectTrigger aria-label="Período">
+      <SelectValue />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="3m">Últimos 3 meses</SelectItem>
+      <SelectItem value="6m">Últimos 6 meses</SelectItem>
+    </SelectContent>
+  </Select>
+  <FullscreenTrigger />
+</Fullscreen>;
+```
+
+### The whole document
+
+useFullscreen takes any element — here document.documentElement — and hands its handle to a control that is not inside any region. Presentation mode for the whole application is this line and nothing else.
+
+Excerpt — not a complete module
+
+```tsx
+const page = useFullscreen(document.documentElement);
+
+<FullscreenTrigger target={page} variant="outline" />;
+```
+
+### The keyboard, key by key
+
+Tab reaches the control, Space or Enter presses it and the reason says keyboard. While full screen, Tab wraps inside the region. Escape in native full screen belongs to the browser — the family writes no listener and reports the leave as escape.
+
+Excerpt — not a complete module
+
+```tsx
+<Fullscreen onFullscreenChange={(next, request) => log(request.reason)}>
+  <FullscreenTrigger />
+</Fullscreen>;
+```
+
+### The control: two variants, three steps, every state
+
+ghost stands in a bar that is already framed, outline over content and carries its own ground. Each step reads the control scale, so the control lines up with a button of the same step. Disabled keeps the words legible and refuses the press.
+
+Excerpt — not a complete module
+
+```tsx
+<FullscreenTrigger size="sm" variant="outline" />;
+```
+
+### The mark alone
+
+iconOnly draws the control square from its height and keeps the words, visually hidden, as its name — so it still says “Exit full screen” to a screen reader when the mark turns inward.
+
+Excerpt — not a complete module
+
+```tsx
+<FullscreenTrigger iconOnly />;
+```
+
+### The control outside the region
+
+A toolbar above a chart holds the control; the chart is the region. useFullscreen gives the handle, target hands it to the control, and the control changes with the chart’s state. Inside the region, a second control takes the reader back.
+
+Excerpt — not a complete module
+
+```tsx
+const [chart, setChart] = useState<HTMLElement | null>(null);
+const handle = useFullscreen(chart);
+
+<>
+  <FullscreenTrigger target={handle} />
+  <section ref={setChart}>…</section>
+</>;
+```
+
+### Defaults once, words and mark of the consumer
+
+A provider sets the control’s step and variant for a subtree. children and icon take a function of the state, so a “Present” control keeps following it; render puts the wiring on the consumer’s own element.
+
+Excerpt — not a complete module
+
+```tsx
+<FullscreenDefaultsProvider size="sm">
+  <Fullscreen>
+    <FullscreenTrigger icon={(on) => (on ? <X size={14} /> : <Presentation size={14} />)}>
+      {(on) => (on ? 'Terminar' : 'Apresentar')}
+    </FullscreenTrigger>
+  </Fullscreen>
+</FullscreenDefaultsProvider>;
+```