lkd-web-kit 0.10.2 → 0.10.3

package/.agents/skills/mantine-combobox/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: mantine-combobox
+description: >
+  Build custom dropdown/select/autocomplete/multiselect components using Mantine's Combobox
+  primitives. Use this skill when: (1) creating a new custom select-like component with
+  Combobox primitives, (2) building a searchable dropdown, (3) implementing a multi-select
+  or tags input variant, (4) customizing option rendering, (5) adding custom filtering logic,
+  or (6) any task involving useCombobox, Combobox.Target, Combobox.Option, or Combobox.Dropdown.
+---
+
+# Mantine Combobox Skill
+
+## Overview
+
+`Combobox` provides low-level primitives for building any select-like UI. The built-in
+`Select`, `Autocomplete`, and `TagsInput` components are all built on top of it.
+
+## Core Workflow
+
+### 1. Create the store
+
+```tsx
+const combobox = useCombobox({
+  onDropdownClose: () => combobox.resetSelectedOption(),
+  onDropdownOpen: () => combobox.selectFirstOption(),
+});
+```
+
+### 2. Render structure
+
+```tsx
+<Combobox store={combobox} onOptionSubmit={handleSubmit}>
+  <Combobox.Target>
+    <InputBase
+      component="button"
+      pointer
+      rightSection={<Combobox.Chevron />}
+      onClick={() => combobox.toggleDropdown()}
+    >
+      {value || <Input.Placeholder>Pick value</Input.Placeholder>}
+    </InputBase>
+  </Combobox.Target>
+  <Combobox.Dropdown>
+    <Combobox.Options>
+      {options.map((item) => (
+        <Combobox.Option value={item} key={item}>{item}</Combobox.Option>
+      ))}
+    </Combobox.Options>
+  </Combobox.Dropdown>
+</Combobox>
+```
+
+### 3. Handle submit
+
+```tsx
+const handleSubmit = (val: string) => {
+  setValue(val);
+  combobox.closeDropdown();
+};
+```
+
+## Target Types
+
+| Scenario | Use |
+|---|---|
+| Button trigger (no text input) | `<Combobox.Target targetType="button">` |
+| Input trigger | `<Combobox.Target>` (default) |
+| Pills + separate input (multi-select) | `<Combobox.DropdownTarget>` + `<Combobox.EventsTarget>` |
+
+## References
+
+- **[`references/api.md`](references/api.md)** — Full API: `useCombobox` options and store, all sub-component props, CSS variables, Styles API selectors
+- **[`references/patterns.md`](references/patterns.md)** — Code examples: searchable select, multi-select with pills, groups, custom rendering, clear button, form integration

package/.agents/skills/mantine-combobox/references/api.md

@@ -0,0 +1,199 @@
+# Combobox API Reference
+
+## Table of Contents
+- [useCombobox hook](#usecombobox-hook)
+- [Combobox (root)](#combobox-root)
+- [Sub-components](#sub-components)
+- [CSS variables & Styles API](#css-variables--styles-api)
+
+---
+
+## useCombobox hook
+
+```tsx
+const combobox = useCombobox(options?: UseComboboxOptions);
+```
+
+**Options:**
+```ts
+interface UseComboboxOptions {
+  defaultOpened?: boolean;
+  opened?: boolean;
+  onOpenedChange?: (opened: boolean) => void;
+  onDropdownClose?: (eventSource: 'keyboard' | 'mouse' | 'unknown') => void;
+  onDropdownOpen?: (eventSource: 'keyboard' | 'mouse' | 'unknown') => void;
+  loop?: boolean;           // Default: true — keyboard nav wraps at boundaries
+  scrollBehavior?: ScrollBehavior; // Default: 'instant'
+}
+```
+
+**Returned store:**
+```ts
+interface ComboboxStore {
+  // Dropdown state
+  dropdownOpened: boolean;
+  openDropdown(eventSource?: 'keyboard' | 'mouse' | 'unknown'): void;
+  closeDropdown(eventSource?: 'keyboard' | 'mouse' | 'unknown'): void;
+  toggleDropdown(eventSource?: 'keyboard' | 'mouse' | 'unknown'): void;
+
+  // Option keyboard navigation
+  selectActiveOption(): string | null;
+  selectFirstOption(): string | null;
+  selectNextOption(): string | null;
+  selectPreviousOption(): string | null;
+  resetSelectedOption(): void;
+  clickSelectedOption(): void;
+  updateSelectedOptionIndex(
+    target?: 'active' | 'selected' | number,
+    options?: { scrollIntoView?: boolean }
+  ): void;
+
+  // Programmatic focus
+  focusSearchInput(): void;
+  focusTarget(): void;
+}
+```
+
+---
+
+## Combobox (root)
+
+```tsx
+<Combobox
+  store={combobox}              // required — ComboboxStore from useCombobox()
+  onOptionSubmit={fn}           // (value: string, optionProps) => void
+  size="sm"                     // MantineSize | string, default: 'sm'
+  dropdownPadding={4}           // number, default: 4
+  resetSelectionOnOptionHover   // boolean
+  readOnly                      // boolean — disables all interactions
+  // + all Popover props (position, offset, width, withinPortal, etc.)
+/>
+```
+
+---
+
+## Sub-components
+
+### Combobox.Target
+```tsx
+<Combobox.Target
+  targetType="input"          // 'button' | 'input', default: 'input'
+  withKeyboardNavigation      // boolean, default: true
+  withAriaAttributes          // boolean, default: true
+  withExpandedAttribute       // boolean, default: false
+  autoComplete="off"          // string
+>
+  {/* single child — the trigger element */}
+</Combobox.Target>
+```
+
+Use `targetType="button"` when the trigger is a button (Space key toggles dropdown).
+
+### Combobox.DropdownTarget
+Marks the element used for dropdown positioning when separate from the keyboard events target. Used together with `Combobox.EventsTarget` in multi-select/pills patterns.
+
+### Combobox.EventsTarget
+Receives keyboard events for dropdown navigation. Used alongside `Combobox.DropdownTarget` when the typing input is nested inside the trigger (e.g. inside `PillsInput`).
+
+### Combobox.Dropdown
+```tsx
+<Combobox.Dropdown hidden={false}>
+  {/* dropdown content */}
+</Combobox.Dropdown>
+```
+
+Use `hidden` to hide without unmounting (preserves scroll position).
+
+### Combobox.Options
+```tsx
+<Combobox.Options labelledBy="some-label-id">
+  {/* Combobox.Option or Combobox.Group elements */}
+</Combobox.Options>
+```
+
+### Combobox.Option
+```tsx
+<Combobox.Option
+  value="react"       // string | number, required
+  active={false}      // visually marks as selected; used by selectActiveOption()
+  disabled={false}
+>
+  React
+</Combobox.Option>
+```
+
+### Combobox.Search
+Built-in search input, wired to keyboard navigation. Renders sticky at top of dropdown.
+
+```tsx
+<Combobox.Search
+  value={search}
+  onChange={(e) => setSearch(e.currentTarget.value)}
+  placeholder="Search..."
+  withAriaAttributes      // boolean, default: true
+  withKeyboardNavigation  // boolean, default: true
+  // + all Input props
+/>
+```
+
+### Combobox.Empty
+```tsx
+<Combobox.Empty>Nothing found</Combobox.Empty>
+```
+
+### Combobox.Group
+```tsx
+<Combobox.Group label="Frontend">
+  <Combobox.Option value="react">React</Combobox.Option>
+</Combobox.Group>
+```
+
+### Combobox.Header / Combobox.Footer
+```tsx
+<Combobox.Header>Custom header</Combobox.Header>
+<Combobox.Footer>Custom footer</Combobox.Footer>
+```
+
+### Combobox.Chevron
+```tsx
+<Combobox.Chevron size="sm" error={error} color="blue" />
+```
+
+### Combobox.ClearButton
+```tsx
+<Combobox.ClearButton onClear={() => setValue(null)} />
+```
+
+### Combobox.HiddenInput
+```tsx
+<Combobox.HiddenInput
+  value={value}           // string | number | (string | number)[] | null
+  valuesDivider=","       // string, default: ','
+  name="myField"
+  form="myForm"
+/>
+```
+
+---
+
+## CSS variables & Styles API
+
+### CSS variables (set on root element)
+| Variable | Description |
+|---|---|
+| `--combobox-option-fz` | Option font size (driven by `size` prop) |
+| `--combobox-option-padding` | Option padding (driven by `size` prop) |
+| `--combobox-padding` | Dropdown padding (driven by `dropdownPadding`, default 4px) |
+
+### Styles API selectors
+| Selector | Element |
+|---|---|
+| `dropdown` | Dropdown container |
+| `options` | Options listbox |
+| `option` | Individual option |
+| `search` | Search input |
+| `empty` | Nothing found message |
+| `header` | Dropdown header |
+| `footer` | Dropdown footer |
+| `group` | Group container |
+| `groupLabel` | Group label text |

package/.agents/skills/mantine-combobox/references/patterns.md

@@ -0,0 +1,279 @@
+# Combobox Implementation Patterns
+
+## Table of Contents
+- [Basic select (button trigger)](#basic-select-button-trigger)
+- [Searchable select (input trigger)](#searchable-select-input-trigger)
+- [Multi-select with pills](#multi-select-with-pills)
+- [Options with groups](#options-with-groups)
+- [Custom option rendering](#custom-option-rendering)
+- [Clear button](#clear-button)
+- [Form integration (hidden input)](#form-integration-hidden-input)
+- [Nothing found message](#nothing-found-message)
+
+---
+
+## Basic select (button trigger)
+
+```tsx
+function CustomSelect({ data }: { data: string[] }) {
+  const [value, setValue] = useState<string | null>(null);
+
+  const combobox = useCombobox({
+    onDropdownClose: () => combobox.resetSelectedOption(),
+  });
+
+  const options = data.map((item) => (
+    <Combobox.Option value={item} key={item} active={item === value}>
+      {item}
+    </Combobox.Option>
+  ));
+
+  return (
+    <Combobox
+      store={combobox}
+      onOptionSubmit={(val) => {
+        setValue(val);
+        combobox.closeDropdown();
+      }}
+    >
+      <Combobox.Target targetType="button">
+        <InputBase
+          component="button"
+          type="button"
+          pointer
+          rightSection={<Combobox.Chevron />}
+          rightSectionPointerEvents="none"
+          onClick={() => combobox.toggleDropdown()}
+        >
+          {value || <Input.Placeholder>Pick value</Input.Placeholder>}
+        </InputBase>
+      </Combobox.Target>
+
+      <Combobox.Dropdown>
+        <Combobox.Options>{options}</Combobox.Options>
+      </Combobox.Dropdown>
+    </Combobox>
+  );
+}
+```
+
+---
+
+## Searchable select (input trigger)
+
+Input acts as both trigger and search field. Filter options based on the typed value.
+
+```tsx
+function SearchableSelect({ data }: { data: string[] }) {
+  const [value, setValue] = useState<string | null>(null);
+  const [search, setSearch] = useState('');
+
+  const combobox = useCombobox({
+    onDropdownClose: () => combobox.resetSelectedOption(),
+    onDropdownOpen: () => combobox.selectFirstOption(),
+  });
+
+  const shouldFilterOptions = data.every((item) => item !== search);
+  const filtered = shouldFilterOptions
+    ? data.filter((item) => item.toLowerCase().includes(search.toLowerCase().trim()))
+    : data;
+
+  const options = filtered.length > 0
+    ? filtered.map((item) => (
+        <Combobox.Option value={item} key={item}>{item}</Combobox.Option>
+      ))
+    : <Combobox.Empty>Nothing found</Combobox.Empty>;
+
+  return (
+    <Combobox
+      store={combobox}
+      onOptionSubmit={(val) => {
+        setValue(val);
+        setSearch(val);
+        combobox.closeDropdown();
+      }}
+    >
+      <Combobox.Target>
+        <InputBase
+          rightSection={<Combobox.Chevron />}
+          value={search}
+          onChange={(e) => {
+            combobox.openDropdown();
+            combobox.updateSelectedOptionIndex();
+            setSearch(e.currentTarget.value);
+          }}
+          onClick={() => combobox.openDropdown()}
+          onFocus={() => combobox.openDropdown()}
+          onBlur={() => {
+            combobox.closeDropdown();
+            setSearch(value || '');
+          }}
+          placeholder="Search value"
+          rightSectionPointerEvents="none"
+        />
+      </Combobox.Target>
+
+      <Combobox.Dropdown>
+        <Combobox.Options>{options}</Combobox.Options>
+      </Combobox.Dropdown>
+    </Combobox>
+  );
+}
+```
+
+---
+
+## Multi-select with pills
+
+Use `Combobox.DropdownTarget` for the outer container and `Combobox.EventsTarget` around the text input inside it.
+
+```tsx
+function MultiSelect({ data }: { data: string[] }) {
+  const combobox = useCombobox({ onDropdownClose: () => combobox.resetSelectedOption() });
+  const [search, setSearch] = useState('');
+  const [value, setValue] = useState<string[]>([]);
+
+  const handleValueSelect = (val: string) =>
+    setValue((current) =>
+      current.includes(val) ? current.filter((v) => v !== val) : [...current, val]
+    );
+
+  const handleValueRemove = (val: string) =>
+    setValue((current) => current.filter((v) => v !== val));
+
+  const options = data
+    .filter((item) => item.toLowerCase().includes(search.trim().toLowerCase()))
+    .map((item) => (
+      <Combobox.Option value={item} key={item} active={value.includes(item)}>
+        <Group gap="sm">
+          {value.includes(item) ? <CheckIcon size={12} /> : null}
+          <span>{item}</span>
+        </Group>
+      </Combobox.Option>
+    ));
+
+  const pills = value.map((item) => (
+    <Pill key={item} withRemoveButton onRemove={() => handleValueRemove(item)}>
+      {item}
+    </Pill>
+  ));
+
+  return (
+    <Combobox store={combobox} onOptionSubmit={handleValueSelect}>
+      <Combobox.DropdownTarget>
+        <PillsInput onClick={() => combobox.openDropdown()}>
+          <Pill.Group>
+            {pills}
+            <Combobox.EventsTarget>
+              <PillsInput.Field
+                onFocus={() => combobox.openDropdown()}
+                onBlur={() => combobox.closeDropdown()}
+                value={search}
+                placeholder="Search values"
+                onChange={(e) => {
+                  combobox.updateSelectedOptionIndex();
+                  setSearch(e.currentTarget.value);
+                }}
+                onKeyDown={(e) => {
+                  if (e.key === 'Backspace' && search.length === 0) {
+                    e.preventDefault();
+                    handleValueRemove(value[value.length - 1]);
+                  }
+                }}
+              />
+            </Combobox.EventsTarget>
+          </Pill.Group>
+        </PillsInput>
+      </Combobox.DropdownTarget>
+
+      <Combobox.Dropdown>
+        <Combobox.Options>
+          {options.length > 0 ? options : <Combobox.Empty>Nothing found</Combobox.Empty>}
+        </Combobox.Options>
+      </Combobox.Dropdown>
+    </Combobox>
+  );
+}
+```
+
+---
+
+## Options with groups
+
+```tsx
+const groups = data.map((group) => (
+  <Combobox.Group label={group.group} key={group.group}>
+    {group.items.map((item) => (
+      <Combobox.Option value={item.value} key={item.value}>
+        {item.label}
+      </Combobox.Option>
+    ))}
+  </Combobox.Group>
+));
+
+// Inside Combobox.Dropdown:
+<Combobox.Options>{groups}</Combobox.Options>
+```
+
+---
+
+## Custom option rendering
+
+Render any content inside `Combobox.Option`:
+
+```tsx
+const options = data.map((item) => (
+  <Combobox.Option value={item.value} key={item.value}>
+    <Group>
+      <Avatar src={item.avatar} size="sm" />
+      <div>
+        <Text size="sm">{item.label}</Text>
+        <Text size="xs" c="dimmed">{item.email}</Text>
+      </div>
+    </Group>
+  </Combobox.Option>
+));
+```
+
+---
+
+## Clear button
+
+```tsx
+const rightSection = value ? (
+  <Combobox.ClearButton onClear={() => { setValue(null); setSearch(''); }} />
+) : (
+  <Combobox.Chevron />
+);
+
+<InputBase
+  rightSection={rightSection}
+  rightSectionPointerEvents={value ? 'all' : 'none'}
+/>
+```
+
+---
+
+## Form integration (hidden input)
+
+```tsx
+// Single value
+<Combobox.HiddenInput value={value} name="framework" />
+
+// Multiple values (joined by comma by default)
+<Combobox.HiddenInput value={selectedValues} name="frameworks" valuesDivider="," />
+```
+
+---
+
+## Nothing found message
+
+```tsx
+<Combobox.Dropdown>
+  <Combobox.Options>
+    {filteredOptions.length > 0
+      ? filteredOptions
+      : <Combobox.Empty>Nothing found for "{search}"</Combobox.Empty>}
+  </Combobox.Options>
+</Combobox.Dropdown>
+```

package/.agents/skills/mantine-custom-components/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: mantine-custom-components
+description: >
+  Build custom components that integrate with Mantine's theming, Styles API, and core features.
+  Use this skill when: (1) creating a new component using factory(), polymorphicFactory(), or
+  genericFactory(), (2) adding Styles API support (classNames, styles, vars, unstyled), (3)
+  implementing CSS variables via createVarsResolver, (4) building compound components with
+  sub-components and shared context, (5) registering a component with MantineProvider via
+  Component.extend(), or (6) any task involving Factory, useProps, useStyles, BoxProps,
+  StylesApiProps, or ElementProps in @mantine/core.
+---
+
+# Mantine Custom Components Skill
+
+## Component template
+
+```tsx
+import {
+  Box, BoxProps, createVarsResolver, ElementProps,
+  factory, Factory, getRadius, MantineRadius,
+  StylesApiProps, useProps, useStyles,
+} from '@mantine/core';
+import classes from './MyComponent.module.css';
+
+export type MyComponentStylesNames = 'root' | 'inner';
+export type MyComponentVariant = 'filled' | 'outline';
+export type MyComponentCssVariables = { root: '--my-radius' };
+
+export interface MyComponentProps
+  extends BoxProps, StylesApiProps<MyComponentFactory>, ElementProps<'div'> {
+  radius?: MantineRadius;
+}
+
+export type MyComponentFactory = Factory<{
+  props: MyComponentProps;
+  ref: HTMLDivElement;
+  stylesNames: MyComponentStylesNames;
+  vars: MyComponentCssVariables;
+  variant: MyComponentVariant;
+}>;
+
+const defaultProps = { radius: 'md' } satisfies Partial<MyComponentProps>;
+
+const varsResolver = createVarsResolver<MyComponentFactory>((_theme, { radius }) => ({
+  root: { '--my-radius': getRadius(radius) },
+}));
+
+export const MyComponent = factory<MyComponentFactory>((_props) => {
+  const props = useProps('MyComponent', defaultProps, _props);
+  const { classNames, className, style, styles, unstyled, vars, attributes, radius, ...others } = props;
+
+  const getStyles = useStyles<MyComponentFactory>({
+    name: 'MyComponent', classes, props,
+    className, style, classNames, styles, unstyled, vars, attributes, varsResolver,
+  });
+
+  return <Box {...getStyles('root')} {...others} />;
+});
+
+MyComponent.displayName = '@mantine/core/MyComponent';
+MyComponent.classes = classes;
+```
+
+## Factory variant — which to use
+
+| Scenario | Factory function | Type |
+|---|---|---|
+| Standard component | `factory()` | `Factory<{}>` |
+| Supports `component` prop (polymorphic) | `polymorphicFactory()` | `PolymorphicFactory<{}>` — add `defaultComponent` and `defaultRef` |
+| Props change based on a generic (e.g. `multiple`) | `genericFactory()` | `Factory<{ signature: ... }>` |
+
+Use `polymorphicFactory` sparingly — it adds TypeScript overhead and slows IDE autocomplete.
+
+## Factory type fields
+
+```ts
+Factory<{
+  props: MyComponentProps;       // required
+  ref: HTMLDivElement;           // element type for the forwarded ref
+  stylesNames: 'root' | 'inner'; // union of Styles API selectors
+  vars: { root: '--my-var' };    // CSS variable map per selector
+  variant: 'filled' | 'outline'; // accepted variant strings
+  staticComponents: {            // sub-components (compound pattern)
+    Item: typeof MyComponentItem;
+  };
+  compound?: boolean;            // true = sub-component; disables theme classNames/styles/vars
+  ctx?: MyContextType;           // passed to styles/vars resolvers as third arg
+  signature?: (...) => JSX.Element; // only for genericFactory
+}>
+```
+
+## Theme integration
+
+Users and the theme can override defaults via `Component.extend()`:
+
+```ts
+const theme = createTheme({
+  components: {
+    MyComponent: MyComponent.extend({
+      defaultProps: { radius: 'xl' },
+      classNames: { root: 'my-root' },
+      styles: { root: { color: 'red' } },
+      vars: (_theme, props) => ({ root: { '--my-radius': getRadius(props.radius) } }),
+    }),
+  },
+});
+```
+
+## References
+
+- **[`references/api.md`](references/api.md)** — All imports: `factory`, `useProps`, `useStyles`, `createVarsResolver`, `createSafeContext`, `StylesApiProps`, `CompoundStylesApiProps`, `BoxProps`, `ElementProps`, theme helpers (`getSize`, `getRadius`, etc.)
+- **[`references/patterns.md`](references/patterns.md)** — Full examples: compound components with context, polymorphic component, generic component, theme integration