@overdoser/react-toolkit 0.0.8 → 0.0.10

package/llms.txt

@@ -193,6 +193,7 @@ Two distinct usage modes — pick one:
 - `align?: 'left' | 'right'` — default `'left'`. Menu alignment relative to trigger.
 - `error?: boolean` — default `false`
 - `fullWidth?: boolean` — default `true`
+- `portal?: boolean` — default `true`. The open menu is rendered in a portal at `document.body` so it escapes `overflow: hidden` ancestors (Modal body, scroll containers). Uses `--crk-z-floating` (1060) which sits above `--crk-z-modal` (1050). Set to `false` if you need the menu in the trigger's DOM subtree (e.g., parent-scoped CSS theming).
 - `id?: string`
 - `onOpen?: () => void`
 - `onClose?: () => void`
@@ -367,6 +368,10 @@ Props:
 - `onValueChange?: (value: string) => void` — single-mode value-only callback.
 - `onValuesChange?: (values: string[]) => void` — multi-mode callback.
 - `clearSearchOnSelect?: boolean` — default `true`. Multi-mode only.
+- `allowCreate?: boolean` — default `false`. Multi-mode only. Adds a "Create '<query>'" row when the search query doesn't match an existing option. Pressing Enter (or clicking the row) pushes the trimmed query into `onValuesChange` and fires `onCreate`.
+- `onCreate?: (value: string) => void` — Multi-mode only, paired with `allowCreate`. Fires with the new value; consumers typically persist it (e.g. push it back into `options`).
+- `createLabel?: (query: string) => ReactNode` — Multi-mode only. Custom render for the create row. Default: `Create "<query>"`.
+- `portal?: boolean` — default `true`. Applies to `searchable` + `multiple` modes (native `<select>` is unaffected). The open menu is rendered in a portal at `document.body` with `position: fixed` + `--crk-z-floating` (1060), so it escapes `overflow: hidden` ancestors and sits above `--crk-z-modal` (1050). Means a `<Select>` inside a `<Modal>` works without needing to size the modal. Pass `false` if you need the menu inside the trigger's subtree.
 - `classes?: Partial<SelectClasses>` where `SelectClasses = { wrapper, root, arrow, search, menu, item, chip, chipRemove }`
 
 Searchable example:

package/manifest.json

@@ -124,6 +124,7 @@
         "align": { "type": "enum", "values": ["left", "right"], "default": "left" },
         "error": { "type": "boolean", "default": false },
         "fullWidth": { "type": "boolean", "default": true },
+        "portal": { "type": "boolean", "default": true, "notes": "Renders the open menu in a portal at document.body using --crk-z-floating (1060). Escapes overflow:hidden ancestors and sits above modals. Set false to keep the menu in the trigger's subtree." },
         "id": { "type": "string" },
         "onOpen": { "type": "() => void" },
         "onClose": { "type": "() => void" },
@@ -253,6 +254,10 @@
         "onValueChange": { "type": "(value: string) => void", "notes": "Single-mode value-only callback." },
         "onValuesChange": { "type": "(values: string[]) => void", "notes": "Multi-mode callback." },
         "clearSearchOnSelect": { "type": "boolean", "default": true, "notes": "Multi-mode only." },
+        "allowCreate": { "type": "boolean", "default": false, "notes": "Multi-mode only. Adds a 'Create <query>' row when the query doesn't match an existing option; pressing Enter (or clicking it) pushes the trimmed query into onValuesChange and fires onCreate." },
+        "onCreate": { "type": "(value: string) => void", "notes": "Multi-mode only. Paired with allowCreate." },
+        "createLabel": { "type": "(query: string) => ReactNode", "notes": "Multi-mode only. Custom render for the Create row." },
+        "portal": { "type": "boolean", "default": true, "notes": "Applies to searchable + multiple modes. Renders the open menu in a portal at document.body using --crk-z-floating (1060) — escapes overflow:hidden ancestors and sits above modals. Set false to keep the menu in the trigger's subtree." },
         "classes": { "type": "Partial<SelectClasses>", "shape": ["wrapper", "root", "arrow", "search", "menu", "item", "chip", "chipRemove"] }
       }
     },
@@ -659,6 +664,8 @@
     "recipes/interactive-line-chart.tsx",
     "recipes/interactive-area-chart.tsx",
     "recipes/interactive-pie-chart.tsx",
-    "recipes/trading-chart.tsx"
+    "recipes/trading-chart.tsx",
+    "recipes/tag-input.tsx",
+    "recipes/multi-select-in-modal.tsx"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overdoser/react-toolkit",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",

package/recipes/multi-select-in-modal.tsx

@@ -0,0 +1,68 @@
+import { useState } from 'react';
+import { Button, Modal, Select } from '@overdoser/react-toolkit';
+
+const TAGS = [
+  { value: 'react', label: 'React' },
+  { value: 'typescript', label: 'TypeScript' },
+  { value: 'rust', label: 'Rust' },
+  { value: 'go', label: 'Go' },
+  { value: 'python', label: 'Python' },
+  { value: 'graphql', label: 'GraphQL' },
+  { value: 'css', label: 'CSS' },
+  { value: 'docker', label: 'Docker' },
+  { value: 'kubernetes', label: 'Kubernetes' },
+  { value: 'postgres', label: 'PostgreSQL' },
+];
+
+/**
+ * Demonstrates that a multi-select dropdown menu renders correctly inside a
+ * `<Modal>`. By default `Select` portals its open menu to `document.body` so
+ * it escapes the modal's `overflow: hidden` clipping — meaning **the modal
+ * does NOT need to be sized large enough** to contain the menu. The menu
+ * uses `--crk-z-floating` (1060) which sits above `--crk-z-modal` (1050).
+ *
+ * If you have a reason to keep the menu inside the modal subtree (e.g.,
+ * parent-scoped CSS theming), pass `portal={false}` and size the modal
+ * generously.
+ */
+export function MultiSelectInModalRecipe() {
+  const [open, setOpen] = useState(false);
+  const [values, setValues] = useState<string[]>([]);
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Edit tags</Button>
+      <Modal open={open} onClose={() => setOpen(false)} size="sm">
+        <Modal.Header onClose={() => setOpen(false)}>Tags</Modal.Header>
+        <Modal.Body>
+          <label style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+            <span style={{ fontSize: 12, color: 'var(--crk-color-text-muted)' }}>
+              Pick all that apply
+            </span>
+            <Select
+              multiple
+              options={TAGS}
+              value={values}
+              onValuesChange={setValues}
+              placeholder="Pick tags…"
+            />
+          </label>
+        </Modal.Body>
+        <Modal.Footer>
+          <Button variant="ghost" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button
+            variant="primary"
+            onClick={() => {
+              // ...persist values, then:
+              setOpen(false);
+            }}
+          >
+            Save
+          </Button>
+        </Modal.Footer>
+      </Modal>
+    </>
+  );
+}

package/recipes/tag-input.tsx

@@ -0,0 +1,71 @@
+import { useState } from 'react';
+import { useForm } from 'react-hook-form';
+import { Button, Form, FormField, Select } from '@overdoser/react-toolkit';
+
+interface TagOption {
+  value: string;
+  label: string;
+}
+
+const INITIAL_TAGS: TagOption[] = [
+  { value: 'react', label: 'React' },
+  { value: 'typescript', label: 'TypeScript' },
+  { value: 'rust', label: 'Rust' },
+  { value: 'go', label: 'Go' },
+  { value: 'python', label: 'Python' },
+];
+
+/**
+ * Tag-input pattern using `<Select multiple allowCreate>`. Users can pick
+ * from existing tags or type a new one + Enter to create it. The freshly
+ * created value is selected immediately; the consumer persists it back into
+ * `options` via `onCreate` so future searches surface it.
+ *
+ * Wired through `<FormField>` to show react-hook-form integration. The
+ * standalone uncontrolled form (no `<Form>`) works just as well — just use
+ * `useState` for the selected values + the options list.
+ */
+export function TagInputRecipe({
+  onSubmit,
+}: {
+  onSubmit?: (values: { tags: string[] }) => void;
+}) {
+  const form = useForm<{ tags: string[] }>({ defaultValues: { tags: [] } });
+  const [options, setOptions] = useState<TagOption[]>(INITIAL_TAGS);
+
+  return (
+    <Form
+      form={form}
+      onSubmit={(values) => onSubmit?.(values)}
+    >
+      <FormField
+        name="tags"
+        label="Tags"
+        helperText="Pick existing tags or type a new one and press Enter"
+      >
+        <Select
+          multiple
+          allowCreate
+          options={options}
+          onCreate={(value) => {
+            // Persist the new tag back into the option list so future searches
+            // find it. Avoid duplicating if a race added it elsewhere.
+            setOptions((prev) =>
+              prev.some((o) => o.value === value) ? prev : [...prev, { value, label: value }],
+            );
+          }}
+          placeholder="Pick or create tags…"
+          searchPlaceholder="Type a tag…"
+          createLabel={(q) => (
+            <>
+              Add tag &ldquo;<strong>{q}</strong>&rdquo;
+            </>
+          )}
+        />
+      </FormField>
+      <Button type="submit" variant="primary">
+        Save
+      </Button>
+    </Form>
+  );
+}