docs: make the API examples compile, render and read as written

bestax-mcp/data/catalog.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": {
     "package": "@allxsmith/bestax-bulma",
-    "version": "5.26.6"
+    "version": "5.27.0"
   },
   "docsBase": "https://bestax.io/docs",
   "categories": [

bestax-mcp/data/components/Autocomplete.json

@@ -7,27 +7,27 @@
   "examples": [
     {
       "title": "Basic Autocomplete",
-      "code": "function example() {\n  const [selected, setSelected] = useState(null);\n  const fruits = [\n    'Apple',\n    'Banana',\n    'Cherry',\n    'Date',\n    'Elderberry',\n    'Fig',\n    'Grape',\n  ];\n\n  return (\n    <Block>\n      <Autocomplete\n        data={fruits}\n        placeholder=\"Search fruit...\"\n        onSelect={setSelected}\n      />\n      {selected && <Paragraph mt=\"2\">Selected: {selected}</Paragraph>}\n    </Block>\n  );\n}"
+      "code": "function example() {\n  const [selected, setSelected] = useState<string | null>(null);\n  const fruits = [\n    'Apple',\n    'Banana',\n    'Cherry',\n    'Date',\n    'Elderberry',\n    'Fig',\n    'Grape',\n  ];\n\n  return (\n    <Block>\n      <Autocomplete\n        data={fruits}\n        placeholder=\"Search fruit...\"\n        onSelect={item => setSelected(typeof item === 'string' ? item : null)}\n      />\n      {selected && <Paragraph mt=\"2\">Selected: {selected}</Paragraph>}\n    </Block>\n  );\n}"
     },
     {
       "title": "Open on Focus",
-      "code": "function example() {\n  const [selected, setSelected] = useState(null);\n  const countries = [\n    'United States',\n    'United Kingdom',\n    'Canada',\n    'Australia',\n    'Germany',\n    'France',\n  ];\n\n  return (\n    <Autocomplete\n      data={countries}\n      placeholder=\"Select a country...\"\n      openOnFocus\n      onSelect={setSelected}\n    />\n  );\n}"
+      "code": "function example() {\n  const countries = [\n    'United States',\n    'United Kingdom',\n    'Canada',\n    'Australia',\n    'Germany',\n    'France',\n  ];\n\n  return (\n    <Autocomplete\n      data={countries}\n      placeholder=\"Select a country...\"\n      openOnFocus\n    />\n  );\n}"
     },
     {
       "title": "With Clear Button",
-      "code": "function example() {\n  const [selected, setSelected] = useState(null);\n  const options = ['Option 1', 'Option 2', 'Option 3', 'Option 4'];\n\n  return (\n    <Autocomplete\n      data={options}\n      placeholder=\"Search options...\"\n      clearable\n      onSelect={setSelected}\n    />\n  );\n}"
+      "code": "function example() {\n  const options = ['Option 1', 'Option 2', 'Option 3', 'Option 4'];\n\n  return (\n    <Autocomplete data={options} placeholder=\"Search options...\" clearable />\n  );\n}"
     },
     {
       "title": "Color and Size Variants",
       "code": "<Block display=\"flex\" flexDirection=\"column\">\n  <Autocomplete\n    data={['Apple', 'Banana', 'Cherry']}\n    placeholder=\"Primary small\"\n    color=\"primary\"\n    size=\"small\"\n  />\n  <Autocomplete\n    data={['Apple', 'Banana', 'Cherry']}\n    placeholder=\"Info normal\"\n    color=\"info\"\n  />\n  <Autocomplete\n    data={['Apple', 'Banana', 'Cherry']}\n    placeholder=\"Success medium\"\n    color=\"success\"\n    size=\"medium\"\n  />\n  <Autocomplete\n    data={['Apple', 'Banana', 'Cherry']}\n    placeholder=\"Danger large\"\n    color=\"danger\"\n    size=\"large\"\n  />\n</Block>"
     },
     {
       "title": "With Object Data",
-      "code": "function example() {\n  const [selected, setSelected] = useState(null);\n  const users = [\n    { value: '1', label: 'John Doe', email: 'john@example.com' },\n    { value: '2', label: 'Jane Smith', email: 'jane@example.com' },\n    { value: '3', label: 'Bob Johnson', email: 'bob@example.com' },\n  ];\n\n  return (\n    <Block>\n      <Autocomplete\n        data={users}\n        field=\"label\"\n        placeholder=\"Search users...\"\n        openOnFocus\n        onSelect={setSelected}\n      />\n      {selected && (\n        <Paragraph mt=\"2\">\n          Selected: {selected.label} ({selected.email})\n        </Paragraph>\n      )}\n    </Block>\n  );\n}"
+      "code": "function example() {\n  const users = [\n    { value: '1', label: 'John Doe', email: 'john@example.com' },\n    { value: '2', label: 'Jane Smith', email: 'jane@example.com' },\n    { value: '3', label: 'Bob Johnson', email: 'bob@example.com' },\n  ];\n  const [selected, setSelected] = useState<(typeof users)[number] | null>(null);\n\n  return (\n    <Block>\n      <Autocomplete\n        data={users}\n        field=\"label\"\n        placeholder=\"Search users...\"\n        openOnFocus\n        onSelect={item =>\n          setSelected(\n            users.find(\n              u => u.value === (typeof item === 'string' ? item : item?.value)\n            ) ?? null\n          )\n        }\n      />\n      {selected && (\n        <Paragraph mt=\"2\">\n          Selected: {selected.label} ({selected.email})\n        </Paragraph>\n      )}\n    </Block>\n  );\n}"
     },
     {
       "title": "Custom Item Template",
-      "code": "function example() {\n  const [selected, setSelected] = useState(null);\n  const users = [\n    { value: '1', label: 'John Doe', role: 'Admin' },\n    { value: '2', label: 'Jane Smith', role: 'Editor' },\n    { value: '3', label: 'Bob Johnson', role: 'Viewer' },\n  ];\n\n  return (\n    <Autocomplete\n      data={users}\n      field=\"label\"\n      placeholder=\"Search users...\"\n      openOnFocus\n      onSelect={setSelected}\n      itemTemplate={item => (\n        <Block display=\"flex\" justifyContent=\"space-between\">\n          <Span>{item.label}</Span>\n          <Tag color=\"info\" light>\n            {item.role}\n          </Tag>\n        </Block>\n      )}\n    />\n  );\n}"
+      "code": "function example() {\n  const users = [\n    { value: '1', label: 'John Doe', role: 'Admin' },\n    { value: '2', label: 'Jane Smith', role: 'Editor' },\n    { value: '3', label: 'Bob Johnson', role: 'Viewer' },\n  ];\n\n  return (\n    <Autocomplete\n      data={users}\n      field=\"label\"\n      placeholder=\"Search users...\"\n      openOnFocus\n      itemTemplate={item => {\n        const user = users.find(\n          u => u.value === (typeof item === 'string' ? item : item.value)\n        );\n        return (\n          <Block display=\"flex\" justifyContent=\"space-between\">\n            <Span>{user?.label}</Span>\n            <Tag color=\"info\" isLight>\n              {user?.role}\n            </Tag>\n          </Block>\n        );\n      }}\n    />\n  );\n}"
     },
     {
       "title": "With Empty State",

bestax-mcp/data/components/Avatar.json

@@ -35,7 +35,7 @@
     },
     {
       "title": "Forwarded ref",
-      "code": "function example() {\n  const avatarRef = React.useRef(null);\n  const [tag, setTag] = React.useState(null);\n\n  return (\n    <>\n      <Avatar ref={avatarRef} name=\"Ada Lovelace\" size=\"64x64\" />\n      <Button mt=\"3\" onClick={() => setTag(avatarRef.current?.tagName)}>\n        Read the tag from its ref\n      </Button>\n      <p>Rendered element: {tag ?? '—'}</p>\n    </>\n  );\n}"
+      "code": "function example() {\n  const avatarRef = React.useRef<HTMLElement>(null);\n  const [tag, setTag] = React.useState<string>();\n\n  return (\n    <>\n      <Avatar ref={avatarRef} name=\"Ada Lovelace\" size=\"64x64\" />\n      <Button mt=\"3\" onClick={() => setTag(avatarRef.current?.tagName)}>\n        Read the tag from its ref\n      </Button>\n      <p>Rendered element: {tag ?? '—'}</p>\n    </>\n  );\n}"
     }
   ],
   "accessibility": "- Image avatars use `alt` (falling back to `name`) for their accessible name.\n- Initials/icon avatars expose `role=\"img\"` and `aria-label` (from `alt`/`name`) — unless\n  rendered as a link or button, where the native link/button role and `aria-label` are used\n  instead. A custom component passed to `as` counts as interactive, since a router link takes\n  `to` rather than this component's `href`. If yours renders something that really is just a\n  picture, say so with `role=\"img\"` and it's treated as one — `alt=\"\"` included. A truthy\n  `aria-hidden` says it too, and so do `role=\"presentation\"` and `role=\"none\"`, though ARIA's\n  own conflict resolution drops those two whenever the avatar still carries a name — prefer\n  `role=\"img\"`. A role claiming the opposite, such as `\"button\"`, doesn't, and neither does an\n  `href`.\n- **Decorative avatars:** pass an explicit `alt=\"\"` when the avatar repeats information\n  already visible next to it (e.g. beside the author's name in a comment row). The image\n  stays decorative and an initials/icon avatar is skipped entirely (`aria-hidden`), avoiding\n  double-speak. The opt-out never applies to a link/button avatar — an interactive element\n  always keeps an accessible name (from `name`, or a generic `\"Avatar\"` fallback) — and a\n  custom component passed to `as` counts as one until it says otherwise, so `alt=\"\"` on a\n  custom wrapper needs that signal next to it.\n- A link/button avatar with no `alt`/`name` (e.g. an API that returns only a photo URL) still\n  gets an `aria-label` fallback rather than rendering a nameless control.\n- `as=\"button\"` defaults to `type=\"button\"`, so a clickable avatar inside a form doesn't\n  submit it.\n- The default fallback icon is `aria-hidden`.",

bestax-mcp/data/components/Button.json

@@ -8,11 +8,11 @@
     { "title": "Default Button", "code": "<Button>Default Button</Button>" },
     {
       "title": "All Colors",
-      "code": "<Buttons>\n  {['primary', 'link', 'info', 'success', 'warning', 'danger'].map(color => (\n    <Button key={color} color={color}>\n      {color.charAt(0).toUpperCase() + color.slice(1)}\n    </Button>\n  ))}\n</Buttons>"
+      "code": "<Buttons>\n  {(['primary', 'link', 'info', 'success', 'warning', 'danger'] as const).map(\n    color => (\n      <Button key={color} color={color}>\n        {color.charAt(0).toUpperCase() + color.slice(1)}\n      </Button>\n    )\n  )}\n</Buttons>"
     },
     {
       "title": "All Sizes",
-      "code": "<Buttons>\n  {['small', 'normal', 'medium', 'large'].map(size => (\n    <Button key={size} size={size}>\n      {size.charAt(0).toUpperCase() + size.slice(1)}\n    </Button>\n  ))}\n</Buttons>"
+      "code": "<Buttons>\n  {(['small', 'normal', 'medium', 'large'] as const).map(size => (\n    <Button key={size} size={size}>\n      {size.charAt(0).toUpperCase() + size.slice(1)}\n    </Button>\n  ))}\n</Buttons>"
     },
     {
       "title": "Light Variant",
@@ -94,7 +94,7 @@
     },
     {
       "title": "Forwarded ref",
-      "code": "function example() {\n  const buttonRef = React.useRef(null);\n  const [tag, setTag] = React.useState(null);\n\n  return (\n    <>\n      <Button color=\"primary\" ref={buttonRef}>\n        Target\n      </Button>\n      <Button ml=\"2\" onClick={() => setTag(buttonRef.current?.tagName)}>\n        Read the tag from its ref\n      </Button>\n      <p>Rendered element: {tag ?? '—'}</p>\n    </>\n  );\n}"
+      "code": "function example() {\n  const buttonRef = React.useRef<HTMLButtonElement>(null);\n  const [tag, setTag] = React.useState<string>();\n\n  return (\n    <>\n      <Button color=\"primary\" ref={buttonRef}>\n        Target\n      </Button>\n      <Button ml=\"2\" onClick={() => setTag(buttonRef.current?.tagName)}>\n        Read the tag from its ref\n      </Button>\n      <p>Rendered element: {tag ?? '—'}</p>\n    </>\n  );\n}"
     }
   ],
   "accessibility": "- **Labeling:** Always provide descriptive content for buttons for screen readers.\n- **States:** The `isDisabled` and `disabled` props ensure correct `aria-disabled` and `disabled` attributes.\n- **Keyboard:** When rendered as `<a>`, disabled buttons are not focusable.\n- **Focus:** Use `isFocused` and `isActive` for visual feedback, but rely on browser focus for actual accessibility.\n\n:::note\nIf your button has only an icon, use `aria-label` to provide accessible text.\n:::",

bestax-mcp/data/components/Buttons.json

@@ -11,11 +11,11 @@
     },
     {
       "title": "All Colors Group",
-      "code": "<Buttons>\n  {['primary', 'link', 'info', 'success', 'warning', 'danger'].map(color => (\n    <Button key={color} color={color}>\n      {color.charAt(0).toUpperCase() + color.slice(1)}\n    </Button>\n  ))}\n</Buttons>"
+      "code": "<Buttons>\n  {(['primary', 'link', 'info', 'success', 'warning', 'danger'] as const).map(\n    color => (\n      <Button key={color} color={color}>\n        {color.charAt(0).toUpperCase() + color.slice(1)}\n      </Button>\n    )\n  )}\n</Buttons>"
     },
     {
       "title": "All Sizes Group",
-      "code": "<Buttons>\n  {['small', 'normal', 'medium', 'large'].map(size => (\n    <Button key={size} size={size}>\n      {size.charAt(0).toUpperCase() + size.slice(1)}\n    </Button>\n  ))}\n</Buttons>"
+      "code": "<Buttons>\n  {(['small', 'normal', 'medium', 'large'] as const).map(size => (\n    <Button key={size} size={size}>\n      {size.charAt(0).toUpperCase() + size.slice(1)}\n    </Button>\n  ))}\n</Buttons>"
     },
     {
       "title": "Group Size",

bestax-mcp/data/components/Carousel.json

@@ -15,7 +15,7 @@
     },
     {
       "title": "Indicator Styles",
-      "code": "function IndicatorExample() {\n  const [style, setStyle] = useState('dots');\n  return (\n    <Block>\n      <Buttons mb=\"4\">\n        <Button\n          onClick={() => setStyle('dots')}\n          color={style === 'dots' ? 'primary' : undefined}\n        >\n          Dots\n        </Button>\n        <Button\n          onClick={() => setStyle('circles')}\n          color={style === 'circles' ? 'primary' : undefined}\n        >\n          Circles\n        </Button>\n        <Button\n          onClick={() => setStyle('lines')}\n          color={style === 'lines' ? 'primary' : undefined}\n        >\n          Lines\n        </Button>\n        <Button\n          onClick={() => setStyle('bars')}\n          color={style === 'bars' ? 'primary' : undefined}\n        >\n          Bars\n        </Button>\n      </Buttons>\n      <Carousel indicatorStyle={style}>\n        <CarouselItem>\n          <Hero color=\"primary\" size=\"medium\">\n            <Hero.Body textAlign=\"centered\">\n              <Paragraph textColor=\"white\">Slide 1</Paragraph>\n            </Hero.Body>\n          </Hero>\n        </CarouselItem>\n        <CarouselItem>\n          <Hero color=\"success\" size=\"medium\">\n            <Hero.Body textAlign=\"centered\">\n              <Paragraph textColor=\"white\">Slide 2</Paragraph>\n            </Hero.Body>\n          </Hero>\n        </CarouselItem>\n        <CarouselItem>\n          <Hero color=\"danger\" size=\"medium\">\n            <Hero.Body textAlign=\"centered\">\n              <Paragraph textColor=\"white\">Slide 3</Paragraph>\n            </Hero.Body>\n          </Hero>\n        </CarouselItem>\n      </Carousel>\n    </Block>\n  );\n}"
+      "code": "function IndicatorExample() {\n  const [style, setStyle] = useState<'dots' | 'circles' | 'lines' | 'bars'>(\n    'dots'\n  );\n  return (\n    <Block>\n      <Buttons mb=\"4\">\n        <Button\n          onClick={() => setStyle('dots')}\n          color={style === 'dots' ? 'primary' : undefined}\n        >\n          Dots\n        </Button>\n        <Button\n          onClick={() => setStyle('circles')}\n          color={style === 'circles' ? 'primary' : undefined}\n        >\n          Circles\n        </Button>\n        <Button\n          onClick={() => setStyle('lines')}\n          color={style === 'lines' ? 'primary' : undefined}\n        >\n          Lines\n        </Button>\n        <Button\n          onClick={() => setStyle('bars')}\n          color={style === 'bars' ? 'primary' : undefined}\n        >\n          Bars\n        </Button>\n      </Buttons>\n      <Carousel indicatorStyle={style}>\n        <CarouselItem>\n          <Hero color=\"primary\" size=\"medium\">\n            <Hero.Body textAlign=\"centered\">\n              <Paragraph textColor=\"white\">Slide 1</Paragraph>\n            </Hero.Body>\n          </Hero>\n        </CarouselItem>\n        <CarouselItem>\n          <Hero color=\"success\" size=\"medium\">\n            <Hero.Body textAlign=\"centered\">\n              <Paragraph textColor=\"white\">Slide 2</Paragraph>\n            </Hero.Body>\n          </Hero>\n        </CarouselItem>\n        <CarouselItem>\n          <Hero color=\"danger\" size=\"medium\">\n            <Hero.Body textAlign=\"centered\">\n              <Paragraph textColor=\"white\">Slide 3</Paragraph>\n            </Hero.Body>\n          </Hero>\n        </CarouselItem>\n      </Carousel>\n    </Block>\n  );\n}"
     },
     {
       "title": "Without Arrows",