bestax-mcp 1.18.28 → 1.18.30

package/data/bulma-classes.json

@@ -13094,6 +13094,8 @@
     }
   ],
   "ownClasses": {
+    "affix": "Affix",
+    "app-frame": "AppFrame",
     "autocomplete": "Autocomplete",
     "avatar": "Avatar",
     "avatars": "Avatars",

package/data/catalog.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "generatedFrom": {
     "package": "@allxsmith/bestax-bulma",
-    "version": "5.59.0"
+    "version": "5.61.0"
   },
   "docsBase": "https://bestax.io/docs",
   "categories": [
@@ -54,6 +54,7 @@
       "id": "components",
       "label": "Components",
       "components": [
+        "Affix",
         "Avatar",
         "Avatars",
         "Badge",
@@ -133,6 +134,7 @@
       "id": "layout",
       "label": "Layout",
       "components": [
+        "AppFrame",
         "Center",
         "Container",
         "Flex",
@@ -164,6 +166,28 @@
     }
   ],
   "components": [
+    {
+      "name": "Affix",
+      "kind": "component",
+      "category": "components",
+      "purpose": "The `Affix` component keeps its content fixed to a corner of the viewport while the page scrolls under it.",
+      "slug": "components/affix",
+      "import": "import { Affix } from '@allxsmith/bestax-bulma';",
+      "compound": false,
+      "propCount": 4,
+      "exampleCount": 8
+    },
+    {
+      "name": "AppFrame",
+      "kind": "component",
+      "category": "layout",
+      "purpose": "The `AppFrame` component lays out an app's pages: a header across the top, a navigation column down the side, the page, and an aside and a footer, with the nav…",
+      "slug": "layout/appframe",
+      "import": "import { AppFrame, useAppFrame } from '@allxsmith/bestax-bulma';",
+      "compound": true,
+      "propCount": 35,
+      "exampleCount": 8
+    },
     {
       "name": "Autocomplete",
       "kind": "component",
@@ -1530,6 +1554,22 @@
     }
   ],
   "cssVarIndex": {
+    "--bulma-affix-offset-horizontal": ["Affix"],
+    "--bulma-affix-offset-vertical": ["Affix"],
+    "--bulma-affix-z-index": ["Affix"],
+    "--bulma-app-frame-aside-width": ["AppFrame"],
+    "--bulma-app-frame-backdrop-background": ["AppFrame"],
+    "--bulma-app-frame-border-color": ["AppFrame"],
+    "--bulma-app-frame-border-width": ["AppFrame"],
+    "--bulma-app-frame-drawer-shadow": ["AppFrame"],
+    "--bulma-app-frame-header-background": ["AppFrame"],
+    "--bulma-app-frame-header-height": ["AppFrame"],
+    "--bulma-app-frame-nav-background": ["AppFrame"],
+    "--bulma-app-frame-nav-padding": ["AppFrame"],
+    "--bulma-app-frame-nav-width": ["AppFrame"],
+    "--bulma-app-frame-skip-link-background": ["AppFrame"],
+    "--bulma-app-frame-skip-link-color": ["AppFrame"],
+    "--bulma-app-frame-transition-duration": ["AppFrame"],
     "--bulma-autocomplete-border-color": ["Autocomplete"],
     "--bulma-autocomplete-border-hover-color": ["Autocomplete"],
     "--bulma-autocomplete-dropdown-background": ["Autocomplete"],
@@ -3080,6 +3120,36 @@
     "--bulma-tree-view-toggle-size": ["TreeView"]
   },
   "documentedWith": {
+    "AppFrameAside": {
+      "component": "AppFrame",
+      "path": "AppFrame.Aside",
+      "purpose": "Content beside the page in an AppFrame, which moves under it below the breakpoint."
+    },
+    "AppFrameBurger": {
+      "component": "AppFrame",
+      "path": "AppFrame.Burger",
+      "purpose": "The button that opens the drawer, or collapses the column from the breakpoint up: Navbar.Burger, wired to the frame."
+    },
+    "AppFrameFooter": {
+      "component": "AppFrame",
+      "path": "AppFrame.Footer",
+      "purpose": "The bottom of an AppFrame, under the page."
+    },
+    "AppFrameHeader": {
+      "component": "AppFrame",
+      "path": "AppFrame.Header",
+      "purpose": "The top bar of an AppFrame, which sticks while the page scrolls."
+    },
+    "AppFrameMain": {
+      "component": "AppFrame",
+      "path": "AppFrame.Main",
+      "purpose": "The page's main content in an AppFrame, which the skip link moves focus to."
+    },
+    "AppFrameNav": {
+      "component": "AppFrame",
+      "path": "AppFrame.Nav",
+      "purpose": "The navigation of an AppFrame: a column beside the page from the breakpoint up, and a drawer below it."
+    },
     "CarouselItem": {
       "component": "Carousel",
       "path": "CarouselItem",

package/data/components/Affix.json

@@ -0,0 +1,135 @@
+{
+  "name": "Affix",
+  "kind": "component",
+  "category": "components",
+  "slug": "components/affix",
+  "docsUrl": "https://bestax.io/docs/api/components/affix",
+  "examples": [
+    {
+      "title": "Basic Usage",
+      "code": "function example() {\n  const [shown, setShown] = useState(false);\n  return (\n    <>\n      <Button onClick={() => setShown(!shown)}>\n        {shown ? 'Hide the Help button' : 'Show the Help button'}\n      </Button>\n      {shown && (\n        <Affix position=\"bottom-left\">\n          <Button color=\"primary\">Help</Button>\n        </Affix>\n      )}\n    </>\n  );\n}"
+    },
+    {
+      "title": "Corners",
+      "code": "import type { AffixPosition } from '@allxsmith/bestax-bulma';\n\nfunction example() {\n  const [position, setPosition] = useState<AffixPosition | null>(null);\n  const corners: AffixPosition[] = [\n    'top-left',\n    'top-right',\n    'bottom-left',\n    'bottom-right',\n  ];\n  return (\n    <>\n      <Buttons>\n        {corners.map(corner => (\n          <Button key={corner} onClick={() => setPosition(corner)}>\n            {corner}\n          </Button>\n        ))}\n        <Button disabled={!position} onClick={() => setPosition(null)}>\n          Hide\n        </Button>\n      </Buttons>\n      {position && (\n        <Affix\n          position={position}\n          mt={position.startsWith('top') ? '6' : undefined}\n          mb={position === 'bottom-right' ? '6' : undefined}\n        >\n          <Button color=\"primary\">Feedback</Button>\n        </Affix>\n      )}\n    </>\n  );\n}"
+    },
+    {
+      "title": "Nudging One Affix",
+      "code": "function example() {\n  const [shown, setShown] = useState(false);\n  return (\n    <>\n      <Button onClick={() => setShown(!shown)}>\n        {shown ? 'Hide the chat button' : 'Show the chat button'}\n      </Button>\n      {shown && (\n        <Affix position=\"bottom-left\" mb=\"6\">\n          <IconButton\n            icon=\"comments\"\n            color=\"link\"\n            isRounded\n            aria-label=\"Open chat\"\n          />\n        </Affix>\n      )}\n    </>\n  );\n}"
+    },
+    {
+      "title": "Offsets and the Safe Area",
+      "code": "<Affix className=\"above-the-tab-bar\">\n  <Button color=\"primary\">Help</Button>\n</Affix>"
+    },
+    {
+      "title": "Out of a Transformed Ancestor",
+      "code": "function example() {\n  const [shown, setShown] = useState(false);\n  return (\n    <>\n      <Button onClick={() => setShown(!shown)}>\n        {shown ? 'Hide the portaled button' : 'Show the portaled button'}\n      </Button>\n      {shown && (\n        <Affix portal position=\"bottom-left\">\n          <Button color=\"primary\">Feedback</Button>\n        </Affix>\n      )}\n    </>\n  );\n}"
+    },
+    {
+      "title": "Several Things in One Corner",
+      "code": "function example() {\n  const [shown, setShown] = useState(false);\n  return (\n    <>\n      <Button onClick={() => setShown(!shown)}>\n        {shown ? 'Hide the buttons' : 'Show the buttons'}\n      </Button>\n      {shown && (\n        <Affix\n          position=\"bottom-left\"\n          display=\"flex\"\n          flexDirection=\"column\"\n          gap=\"2\"\n        >\n          <IconButton icon=\"comments\" color=\"link\" aria-label=\"Open chat\" />\n          <IconButton icon=\"question\" color=\"primary\" aria-label=\"Help\" />\n        </Affix>\n      )}\n    </>\n  );\n}"
+    },
+    {
+      "title": "A Consent Notice",
+      "code": "function example() {\n  const [shown, setShown] = useState(false);\n  return (\n    <>\n      <Button onClick={() => setShown(true)}>Show the notice</Button>\n      {shown && (\n        <Affix position=\"bottom-left\">\n          <Box role=\"region\" aria-label=\"Cookie consent\" mb=\"0\">\n            <ScrollArea\n              maxHeight=\"calc(100dvh - 2 * var(--bulma-affix-offset-vertical) - env(safe-area-inset-top, 0px) - env(safe-area-inset-bottom, 0px) - 7rem)\"\n              aria-label=\"What we store\"\n              mb=\"3\"\n            >\n              <Paragraph>\n                We use one cookie to remember your theme. Nothing else is\n                stored, and nothing is shared.\n              </Paragraph>\n            </ScrollArea>\n            <Buttons>\n              <Button color=\"primary\" onClick={() => setShown(false)}>\n                Accept\n              </Button>\n              <Button onClick={() => setShown(false)}>Decline</Button>\n            </Buttons>\n          </Box>\n        </Affix>\n      )}\n    </>\n  );\n}"
+    },
+    {
+      "title": "Right-to-Left",
+      "code": "function example() {\n  const [shown, setShown] = useState(false);\n  return (\n    <LocaleProvider locale=\"ar\" dir=\"rtl\">\n      <Button onClick={() => setShown(!shown)}>\n        {shown ? 'إخفاء' : 'إظهار'}\n      </Button>\n      {shown && (\n        <Affix position=\"bottom-left\">\n          <Button color=\"primary\">ملاحظات</Button>\n        </Affix>\n      )}\n    </LocaleProvider>\n  );\n}"
+    }
+  ],
+  "accessibility": "- **No role:** it's a positioning wrapper, and what's inside keeps its own role. Content that needs\n  a landmark, such as a consent notice, brings its own `role=\"region\"` and name, as in\n  [A Consent Notice](https://bestax.io/docs/api/components/affix#a-consent-notice).\n- **Reading and Tab order are DOM order:** the corner it shows in says nothing about when a screen\n  reader or the Tab key reaches it. In place, that's where you write it, so put it where it belongs\n  in the reading order, usually after the page's main content. With `portal` it's appended to its\n  container when it mounts, so it comes after what's already there.\n- **Focus not obscured:** a fixed box can cover a focused link near its corner, which fails\n  [WCAG 2.4.11](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum) when it\n  hides it entirely. On a page with a bottom-corner Affix, give `html` a `scroll-padding-bottom` at\n  least its height plus its offset\n  ([technique C43](https://www.w3.org/WAI/WCAG22/Techniques/css/C43)), so a link that Tab scrolls\n  into view stops above it, and leave as much room at the end of the page, so the last link can\n  scroll clear too:\n\n  ```css\n  html {\n    scroll-padding-bottom: 5rem;\n  }\n\n  main {\n    padding-bottom: 5rem;\n  }\n  ```\n\n  A top-corner Affix takes `scroll-padding-top` the same way. Not every browser scrolls to a\n  focused link that's already on screen, so the padding lowers the odds rather than ruling it out,\n  and a small Affix leaves less of the page under it.\n\n- **Reflow:** it's never wider than the viewport less its offsets, at 320px too, so its text wraps\n  rather than running off the side. It doesn't scroll, so content that can be taller than the\n  screen at high zoom has to scroll itself, as in [A Consent Notice](https://bestax.io/docs/api/components/affix#a-consent-notice), with the\n  controls that matter outside the scrolling part. A fixed box takes a bigger share of the screen\n  at high zoom, so keep what's in it small.\n- **Forced colors:** it draws nothing of its own, so what's inside keeps its own forced colors.\n- **Motion:** it has no motion of its own. What's inside keeps its own transitions.\n- **Right-to-left:** the corner stays where `position` puts it. See\n  [Right-to-Left](https://bestax.io/docs/api/components/affix#right-to-left).",
+  "related": [
+    "Badge",
+    "Box",
+    "Button",
+    "Modal",
+    "Portal",
+    "ScrollArea",
+    "Toast",
+    "useBulmaClasses"
+  ],
+  "storybook": "https://bestax.io/storybook/?path=/story/components-affix--default",
+  "summary": "The `Affix` component keeps its content fixed to a corner of the viewport while the page scrolls under it. It's a `<div>` with no role, so what's inside keeps its own. It sits `--bulma-affix-offset-vertical` and `--bulma-affix-offset-horizontal` from its corner's edges, plus the device's safe-area inset, and stacks at `--bulma-affix-z-index`, over the page's content and under its navbar, static or fixed, its menus, popovers, the Sidebar, the modals, Tooltip and Toast. It's as wide as its content and never wider than the viewport less its offsets. It doesn't scroll, so nothing inside it is clipped, and content that can be taller than the screen scrolls itself. Its place in the reading and Tab order is its place in the DOM, whatever corner it shows in.",
+  "import": "import { Affix } from '@allxsmith/bestax-bulma';",
+  "sourceFile": "bulma-ui/src/components/Affix.tsx",
+  "rootClass": "affix",
+  "parts": [
+    {
+      "path": "Affix",
+      "summary": "The `Affix` component keeps its content fixed to a corner of the viewport while the page scrolls under it. It's a `<div>` with no role, so what's inside keeps its own. It sits `--bulma-affix-offset-vertical` and `--bulma-affix-offset-horizontal` from its corner's edges, plus the device's safe-area inset, and stacks at `--bulma-affix-z-index`, over the page's content and under its navbar, static or fixed, its menus, popovers, the Sidebar, the modals, Tooltip and Toast. It's as wide as its content and never wider than the viewport less its offsets. It doesn't scroll, so nothing inside it is clipped, and content that can be taller than the screen scrolls itself. Its place in the reading and Tab order is its place in the DOM, whatever corner it shows in.",
+      "component": null,
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "Additional CSS classes to apply.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "children",
+          "type": "React.ReactNode",
+          "default": null,
+          "description": "What stays in the corner.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "position",
+          "type": "'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'",
+          "default": "'bottom-right'",
+          "description": "The corner of the viewport it's fixed to. Physical, as Badge's and Toast's are: `'bottom-right'` stays on the right in right-to-left text. Its distance from the edges is `--bulma-affix-offset-vertical` and `--bulma-affix-offset-horizontal` plus the device's safe-area inset; a margin from the spacing helpers (`mb`, `mr`, …) adds to it. A margin on one side also takes that much of the width its content can have, which the offset variables don't, so move it far with those.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        },
+        {
+          "name": "portal",
+          "type": "boolean | string | HTMLElement",
+          "default": "false",
+          "description": "Renders it into another container, for a page where an ancestor's `transform`, `filter` or `contain` would capture `position: fixed`. `true` portals to the `portalContainer` a `ConfigProvider` sets, `document.body` by default; a string is used as a `document.querySelector` selector; an element is used directly. Renders in place on the server and while hydrating, moving into the portal once the client takes over, so hydration matches. Portaled, it's appended to that container when it mounts, so it comes after what's already there in the reading and Tab order.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        }
+      ],
+      "extraProps": [
+        {
+          "name": "ref",
+          "type": "React.Ref<HTMLDivElement>",
+          "default": null,
+          "description": "Ref forwarded to the `<div>`, wherever it renders.",
+          "required": false,
+          "inherited": false,
+          "deprecated": false
+        }
+      ],
+      "catchAll": "All standard <div> attributes and Bulma helper props",
+      "types": []
+    }
+  ],
+  "cssVars": [
+    {
+      "css": "--bulma-affix-offset-vertical",
+      "sass": "$affix-offset-vertical",
+      "default": "$block-spacing",
+      "scope": "root"
+    },
+    {
+      "css": "--bulma-affix-offset-horizontal",
+      "sass": "$affix-offset-horizontal",
+      "default": "$block-spacing",
+      "scope": "root"
+    },
+    {
+      "css": "--bulma-affix-z-index",
+      "sass": "$affix-z-index",
+      "default": "$extras-z-index-dropdown - 1",
+      "scope": "root"
+    }
+  ]
+}