{"name":"cascade-select","title":"Cascade Select","description":"A hierarchical select with cascading panels for drilling down through nested options, e.g. Region > Country > City.","installCommand":"bunx marko-ui add cascade-select -y","usageTags":"<CascadeSelect>","importSnippet":"import CascadeSelect from \"@/components/ui/cascade-select/cascade-select.marko\";","usageSnippet":"static const items = [\n  {\n    value: \"europe\",\n    label: \"Europe\",\n    children: [\n      { value: \"france\", label: \"France\", children: [{ value: \"paris\", label: \"Paris\" }] },\n    ],\n  },\n];\n\n<CascadeSelect items=items placeholder=\"Select a city\" label=\"Region / Country / City\"/>","tags":["CascadeSelect"],"parts":[{"name":"option","attributes":[{"name":"value","type":"string","required":true},{"name":"label","type":"string","required":true},{"name":"disabled","type":"boolean","required":false}],"repeatable":true}],"props":[{"name":"allowParentSelection","type":"boolean","required":false,"description":"Whether parent (branch) items can be selectable"},{"name":"closeOnSelect","type":"boolean | undefined","required":false,"default":"true","description":"Whether the cascade-select should close when an item is selected"},{"name":"defaultHighlightedValue","type":"string[] | undefined","required":false,"description":"The initial highlighted value of the cascade-select when rendered."},{"name":"defaultOpen","type":"boolean | undefined","required":false,"description":"The initial open state of the cascade-select when rendered.\nUse when you don't need to control the open state."},{"name":"defaultValue","type":"string[][] | undefined","required":false,"description":"The initial value of the cascade-select when rendered.\nUse when you don't need to control the value."},{"name":"dir","type":"'ltr' | 'rtl' | undefined","required":false,"default":"ltr","description":"The document's text/writing direction."},{"name":"disabled","type":"boolean | undefined","required":false,"description":"Whether the cascade-select is disabled"},{"name":"form","type":"string | undefined","required":false,"description":"The form attribute of the underlying input element"},{"name":"formatValue","type":"((selectedItems: T[][]) => string) | undefined","required":false,"description":"Function to format the display value"},{"name":"getRootNode","type":"(() => ShadowRoot | Document | Node) | undefined","required":false,"description":"A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron."},{"name":"highlightedValue","type":"string[] | undefined","required":false,"description":"The controlled highlighted value of the cascade-select"},{"name":"highlightTrigger","type":"'click' | 'hover' | undefined","required":false,"default":"click","description":"What triggers highlighting of items"},{"name":"ids","type":"ElementIds | undefined","required":false,"description":"The ids of the cascade-select elements. Useful for composition."},{"name":"invalid","type":"boolean | undefined","required":false,"description":"Whether the cascade-select is invalid"},{"name":"items","type":"CascadeSelectItem[]","required":false},{"name":"label","type":"string","required":false},{"name":"loopFocus","type":"boolean | undefined","required":false,"default":"false","description":"Whether the cascade-select should loop focus when navigating with keyboard"},{"name":"multiple","type":"boolean | undefined","required":false,"default":"false","description":"Whether to allow multiple selections"},{"name":"name","type":"string | undefined","required":false,"description":"The name attribute of the underlying input element"},{"name":"open","type":"boolean | undefined","required":false,"description":"The controlled open state of the cascade-select"},{"name":"placeholder","type":"string","required":false},{"name":"positioning","type":"PositioningOptions | undefined","required":false,"description":"The positioning options for the cascade-select content"},{"name":"readOnly","type":"boolean | undefined","required":false,"description":"Whether the cascade-select is read-only"},{"name":"required","type":"boolean | undefined","required":false,"description":"Whether the cascade-select is required"},{"name":"scrollToIndexFn","type":"((details: ScrollToIndexDetails) => void) | undefined","required":false,"description":"Function to scroll to a specific index in a list"},{"name":"value","type":"string[][] | undefined","required":false,"description":"The controlled value of the cascade-select"}],"events":[{"name":"onFocusOutside","arg":"FocusOutsideEvent","description":"Function called when the focus is moved outside the component"},{"name":"onHighlightChange","arg":"HighlightChangeDetails<T>","description":"Called when the highlighted value changes"},{"name":"onInteractOutside","arg":"InteractOutsideEvent","description":"Function called when an interaction happens outside the component"},{"name":"onOpenChange","arg":"OpenChangeDetails","description":"Called when the open state changes"},{"name":"onPointerDownOutside","arg":"PointerDownOutsideEvent","description":"Function called when the pointer is pressed down outside the component"},{"name":"onValueChange","arg":"ValueChangeDetails<T>","description":"Called when the value changes"},{"name":"valueChange","arg":"string[][]"}],"keyboard":[],"accessibilityNotes":[],"examples":[{"id":"cascade-select-demo","title":"Default","source":"import CascadeSelect from \"@marko-ui/shadcn/ui/cascade-select/cascade-select.marko\";\n\nstatic const locations = [\n  {\n    value: \"asia\",\n    label: \"Asia\",\n    children: [\n      {\n        value: \"india\",\n        label: \"India\",\n        children: [\n          { value: \"mumbai\", label: \"Mumbai\" },\n          { value: \"delhi\", label: \"Delhi\" },\n          { value: \"bangalore\", label: \"Bangalore\" },\n        ],\n      },\n      {\n        value: \"japan\",\n        label: \"Japan\",\n        children: [\n          { value: \"tokyo\", label: \"Tokyo\" },\n          { value: \"osaka\", label: \"Osaka\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"europe\",\n    label: \"Europe\",\n    children: [\n      {\n        value: \"france\",\n        label: \"France\",\n        children: [\n          { value: \"paris\", label: \"Paris\" },\n          { value: \"lyon\", label: \"Lyon\" },\n        ],\n      },\n      {\n        value: \"germany\",\n        label: \"Germany\",\n        children: [\n          { value: \"berlin\", label: \"Berlin\" },\n          { value: \"munich\", label: \"Munich\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"north-america\",\n    label: \"North America\",\n    disabled: true,\n    children: [\n      { value: \"usa\", label: \"United States\" },\n      { value: \"canada\", label: \"Canada\" },\n    ],\n  },\n];\n\n<CascadeSelect items=locations placeholder=\"Select a city\" label=\"Region / Country / City\"/>","description":"Each level of the `items` tree opens a new panel as you drill down."},{"id":"cascade-select-default-value","title":"Default value","source":"import CascadeSelect from \"@marko-ui/shadcn/ui/cascade-select/cascade-select.marko\";\n\nstatic const locations = [\n  {\n    value: \"asia\",\n    label: \"Asia\",\n    children: [\n      {\n        value: \"india\",\n        label: \"India\",\n        children: [\n          { value: \"mumbai\", label: \"Mumbai\" },\n          { value: \"delhi\", label: \"Delhi\" },\n          { value: \"bangalore\", label: \"Bangalore\" },\n        ],\n      },\n      {\n        value: \"japan\",\n        label: \"Japan\",\n        children: [\n          { value: \"tokyo\", label: \"Tokyo\" },\n          { value: \"osaka\", label: \"Osaka\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"europe\",\n    label: \"Europe\",\n    children: [\n      {\n        value: \"france\",\n        label: \"France\",\n        children: [\n          { value: \"paris\", label: \"Paris\" },\n          { value: \"lyon\", label: \"Lyon\" },\n        ],\n      },\n      {\n        value: \"germany\",\n        label: \"Germany\",\n        children: [\n          { value: \"berlin\", label: \"Berlin\" },\n          { value: \"munich\", label: \"Munich\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"north-america\",\n    label: \"North America\",\n    disabled: true,\n    children: [\n      { value: \"usa\", label: \"United States\" },\n      { value: \"canada\", label: \"Canada\" },\n    ],\n  },\n];\n\n<CascadeSelect\n  items=locations\n  defaultValue=[[\"europe\", \"germany\", \"berlin\"]]\n  placeholder=\"Select a city\"\n  label=\"Region / Country / City\"\n/>","description":"Pass `value` as a list of path arrays to select a leaf on mount."},{"id":"cascade-select-disabled-items","title":"Disabled items","source":"import CascadeSelect from \"@marko-ui/shadcn/ui/cascade-select/cascade-select.marko\";\n\nstatic const locationsWithDisabled = [\n  {\n    value: \"asia\",\n    label: \"Asia\",\n    children: [\n      { value: \"india\", label: \"India\", disabled: true },\n      { value: \"japan\", label: \"Japan\" },\n    ],\n  },\n  {\n    value: \"europe\",\n    label: \"Europe\",\n    children: [\n      { value: \"france\", label: \"France\" },\n      { value: \"germany\", label: \"Germany\" },\n    ],\n  },\n];\n\n<CascadeSelect items=locationsWithDisabled placeholder=\"Select a city\" label=\"Region / Country\"/>","description":"Mark an individual item `disabled` to skip it in navigation and selection."},{"id":"cascade-select-controlled","title":"Controlled","source":"import CascadeSelect from \"@marko-ui/shadcn/ui/cascade-select/cascade-select.marko\";\n\nstatic const locations = [\n  {\n    value: \"asia\",\n    label: \"Asia\",\n    children: [\n      {\n        value: \"india\",\n        label: \"India\",\n        children: [\n          { value: \"mumbai\", label: \"Mumbai\" },\n          { value: \"delhi\", label: \"Delhi\" },\n          { value: \"bangalore\", label: \"Bangalore\" },\n        ],\n      },\n      {\n        value: \"japan\",\n        label: \"Japan\",\n        children: [\n          { value: \"tokyo\", label: \"Tokyo\" },\n          { value: \"osaka\", label: \"Osaka\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"europe\",\n    label: \"Europe\",\n    children: [\n      {\n        value: \"france\",\n        label: \"France\",\n        children: [\n          { value: \"paris\", label: \"Paris\" },\n          { value: \"lyon\", label: \"Lyon\" },\n        ],\n      },\n      {\n        value: \"germany\",\n        label: \"Germany\",\n        children: [\n          { value: \"berlin\", label: \"Berlin\" },\n          { value: \"munich\", label: \"Munich\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"north-america\",\n    label: \"North America\",\n    disabled: true,\n    children: [\n      { value: \"usa\", label: \"United States\" },\n      { value: \"canada\", label: \"Canada\" },\n    ],\n  },\n];\n\n<let/value=[[\"asia\", \"japan\", \"tokyo\"]]/>\n\n<div class=\"space-y-2\">\n  <CascadeSelect\n    items=locations\n    value=value\n    valueChange(next) { value = next; }\n    placeholder=\"Select a city\"\n    label=\"Region / Country / City\"\n  />\n  <p class=\"text-sm text-muted-foreground\">Selected: ${JSON.stringify(value)}</p>\n</div>","description":"Zag machines are controlled: a `value` prop without a change handler never moves. Pair it with `valueChange`.","essential":true},{"id":"cascade-select-disabled","title":"Disabled","source":"import CascadeSelect from \"@marko-ui/shadcn/ui/cascade-select/cascade-select.marko\";\n\nstatic const locations = [\n  {\n    value: \"asia\",\n    label: \"Asia\",\n    children: [\n      {\n        value: \"india\",\n        label: \"India\",\n        children: [\n          { value: \"mumbai\", label: \"Mumbai\" },\n          { value: \"delhi\", label: \"Delhi\" },\n          { value: \"bangalore\", label: \"Bangalore\" },\n        ],\n      },\n      {\n        value: \"japan\",\n        label: \"Japan\",\n        children: [\n          { value: \"tokyo\", label: \"Tokyo\" },\n          { value: \"osaka\", label: \"Osaka\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"europe\",\n    label: \"Europe\",\n    children: [\n      {\n        value: \"france\",\n        label: \"France\",\n        children: [\n          { value: \"paris\", label: \"Paris\" },\n          { value: \"lyon\", label: \"Lyon\" },\n        ],\n      },\n      {\n        value: \"germany\",\n        label: \"Germany\",\n        children: [\n          { value: \"berlin\", label: \"Berlin\" },\n          { value: \"munich\", label: \"Munich\" },\n        ],\n      },\n    ],\n  },\n  {\n    value: \"north-america\",\n    label: \"North America\",\n    disabled: true,\n    children: [\n      { value: \"usa\", label: \"United States\" },\n      { value: \"canada\", label: \"Canada\" },\n    ],\n  },\n];\n\n<CascadeSelect items=locations placeholder=\"Select a city\" label=\"Region / Country / City\" disabled/>","description":"Pass `disabled` to disable the whole control."},{"id":"cascade-select-compound","title":"Compound (attr tags)","source":"import CascadeSelect from \"@marko-ui/shadcn/ui/cascade-select/cascade-select.marko\";\n\n<CascadeSelect placeholder=\"Select a fruit\" label=\"Fruit\">\n  <@option value=\"apple\" label=\"Apple\"/>\n  <@option value=\"banana\" label=\"Banana\"/>\n  <@option value=\"cherry\" label=\"Cherry\"/>\n  <@option value=\"durian\" label=\"Durian\" disabled/>\n</CascadeSelect>","description":"Use `<@option>` attribute tags for a flat list of options instead of `items=`. Attribute tags don't recurse into children — use `items=` for real trees.","essential":true}],"importInstallCommand":"bun add @marko-ui/shadcn marko-zag","nativeAttributes":"div","itemTypes":[{"prop":"items","typeName":"CascadeSelectItem","fields":[{"name":"value","type":"string","required":true},{"name":"label","type":"string","required":true},{"name":"disabled","type":"boolean","required":false},{"name":"children","type":"CascadeSelectItem[]","required":false}]}]}