lkd-web-kit 0.10.2 → 0.10.3

package/.agents/skills/mantine-custom-components/references/api.md

@@ -0,0 +1,407 @@
+# Custom Components API Reference
+
+## Table of Contents
+- [Imports cheatsheet](#imports-cheatsheet)
+- [factory / polymorphicFactory / genericFactory](#factory--polymorphicfactory--genericfactory)
+- [Factory type fields](#factory-type-fields)
+- [useProps](#usepropss)
+- [useStyles](#usestyles)
+- [createVarsResolver](#createvarsresolver)
+- [StylesApiProps and CompoundStylesApiProps](#stylesapiprops-and-compoundstylesapiprops)
+- [BoxProps and ElementProps](#boxprops-and-elementprops)
+- [createSafeContext](#createsafecontext)
+- [Theme helper functions](#theme-helper-functions)
+- [Static properties](#static-properties)
+
+---
+
+## Imports cheatsheet
+
+```ts
+import {
+  // Factory functions
+  factory,
+  polymorphicFactory,
+  genericFactory,
+
+  // Types
+  Factory,
+  PolymorphicFactory,
+  StylesApiProps,
+  CompoundStylesApiProps,
+  BoxProps,
+  ElementProps,
+
+  // Hooks
+  useProps,
+  useStyles,
+
+  // Vars
+  createVarsResolver,
+
+  // Context
+  createSafeContext,
+
+  // Base component
+  Box,
+
+  // Theme helpers
+  getSize,
+  getSpacing,
+  getRadius,
+  getFontSize,
+  getLineHeight,
+  getShadow,
+  rem,
+  em,
+} from '@mantine/core';
+```
+
+---
+
+## factory / polymorphicFactory / genericFactory
+
+### factory()
+
+Standard factory for non-polymorphic components.
+
+```ts
+factory<Payload extends FactoryPayload>(
+  ui: (props: Payload['props'] & { ref?: React.Ref<Payload['ref']> }) => React.ReactNode
+): MantineComponent<Payload>
+```
+
+The returned component has static properties: `.extend()`, `.withProps()`, `.classes`, `.displayName`, `.varsResolver` (if vars are used), and any sub-components assigned.
+
+### polymorphicFactory()
+
+For components that accept a `component` prop to render as a different element. Same signature as `factory()`, but uses `PolymorphicFactory` type.
+
+```ts
+// Type uses PolymorphicFactory<{}> instead of Factory<{}>
+export type MyFactory = PolymorphicFactory<{
+  props: MyProps;
+  defaultRef: HTMLButtonElement;    // default ref type
+  defaultComponent: 'button';       // default element
+  stylesNames: ...;
+  vars: ...;
+}>;
+
+export const My = polymorphicFactory<MyFactory>((_props) => { ... });
+```
+
+### genericFactory()
+
+For components whose prop types depend on a generic argument.
+
+```ts
+// Factory uses 'signature' field
+export type MyFactory = Factory<{
+  props: MyProps<boolean>;
+  signature: <T extends boolean = false>(props: MyProps<T>) => React.JSX.Element;
+  ref: HTMLDivElement;
+  // ... other fields
+}>;
+
+export const My = genericFactory<MyFactory>((_props) => { ... });
+```
+
+---
+
+## Factory type fields
+
+All fields except `props` are optional.
+
+```ts
+Factory<{
+  props: MyComponentProps;
+
+  // Forwarded ref element type
+  ref: HTMLDivElement;
+
+  // Union of Styles API selector strings (must match CSS module class names)
+  stylesNames: 'root' | 'label' | 'icon';
+
+  // CSS variables definition: { selectorName: '--var-name' | '--other-var' }
+  vars: {
+    root: '--my-height' | '--my-color';
+    label: '--my-label-fz';
+  };
+
+  // Accepted values for the variant prop
+  variant: 'filled' | 'outline' | 'subtle';
+
+  // Sub-components for compound pattern
+  staticComponents: {
+    Item: typeof MyItem;
+    Label: typeof MyLabel;
+  };
+
+  // Set to true for sub-components — disables theme classNames/styles/vars for this component
+  compound: true;
+
+  // Context type passed as 3rd argument to styles/vars resolvers
+  ctx: { opened: boolean };
+
+  // Generic signature (genericFactory only)
+  signature: <T extends boolean = false>(props: MyProps<T>) => React.JSX.Element;
+}>
+```
+
+---
+
+## useProps
+
+Merges default props from three sources in priority order (highest → lowest):
+1. Props passed by the user
+2. Default props from `MantineProvider` theme (`components.MyComponent.defaultProps`)
+3. Component-level `defaultProps`
+
+```ts
+useProps<T extends Record<string, any>>(
+  componentName: string,    // must match the name used in theme.components
+  defaultProps: Partial<T>, // use 'satisfies Partial<T>' for correct inference
+  props: T
+): T
+```
+
+**Important:** Always call `useProps` before destructuring. Always use `satisfies Partial<Props>` (not `: Partial<Props>`) for `defaultProps` to preserve narrowed types.
+
+```ts
+const defaultProps = { size: 'md', variant: 'filled' } satisfies Partial<MyProps>;
+
+const props = useProps('MyComponent', defaultProps, _props);
+const { className, style, classNames, styles, unstyled, vars, attributes, ...others } = props;
+```
+
+---
+
+## useStyles
+
+Returns a `getStyles` function that provides `className` and `style` for each Styles API selector.
+
+```ts
+useStyles<Payload extends FactoryPayload>(input: {
+  name: string | string[];       // component name(s) for static CSS class generation
+  classes: Record<string, string>; // CSS module classes object
+  props: Payload['props'];
+  stylesCtx?: Payload['ctx'];    // optional context for styles/vars resolvers
+  className?: string;            // spread to rootSelector
+  style?: MantineStyleProp;      // spread to rootSelector
+  rootSelector?: string;         // which selector gets className/style (default: 'root')
+  unstyled?: boolean;
+  classNames?: ClassNames<Payload>;
+  styles?: Styles<Payload>;
+  vars?: PartialVarsResolver<Payload>;
+  varsResolver?: VarsResolver<Payload>;
+  attributes?: Attributes<Payload>;
+}): GetStylesApi<Payload>
+```
+
+**`getStyles` function:**
+```ts
+getStyles(
+  selector: StylesNames,
+  options?: {
+    className?: string;   // additional className merged in
+    style?: CSSProperties; // additional style merged in
+    focusable?: boolean;
+    active?: boolean;
+    withStaticClass?: boolean;
+  }
+): { className: string; style: CSSProperties }
+```
+
+Usage:
+```tsx
+<Box {...getStyles('root')} {...others} />
+<div {...getStyles('label', { className: cx(extraClass), style: { color: 'red' } })} />
+```
+
+---
+
+## createVarsResolver
+
+Defines how component props map to CSS variables.
+
+```ts
+createVarsResolver<Payload extends FactoryPayload>(
+  resolver: (
+    theme: MantineTheme,
+    props: Payload['props'],
+    ctx: Payload['ctx']    // only if Factory has ctx field
+  ) => TransformVars<Payload['vars']>
+): VarsResolver<Payload>
+```
+
+The resolver must return an object matching the `vars` structure defined in `Factory`:
+
+```ts
+// Factory vars: { root: '--my-height' | '--my-color' }
+const varsResolver = createVarsResolver<MyFactory>((_theme, { size, color }) => ({
+  root: {
+    '--my-height': getSize(size, 'my-height'),
+    '--my-color': color ?? undefined,   // undefined = CSS var not set (uses CSS fallback)
+  },
+}));
+```
+
+Assign to the component after creation:
+```ts
+MyComponent.varsResolver = varsResolver;
+```
+
+---
+
+## StylesApiProps and CompoundStylesApiProps
+
+**`StylesApiProps`** — extend on the root/main component's props interface:
+```ts
+interface StylesApiProps<Payload extends FactoryPayload> {
+  unstyled?: boolean;
+  variant?: Payload['variant'] | (string & {});
+  classNames?: ClassNames<Payload>;    // { root: 'my-class', inner: 'other' } or callback
+  styles?: Styles<Payload>;            // { root: { color: 'red' } } or callback
+  vars?: PartialVarsResolver<Payload>; // (theme, props) => { root: { '--my-var': '...' } }
+  attributes?: Attributes<Payload>;    // { root: { 'data-custom': value } }
+}
+```
+
+**`CompoundStylesApiProps`** — extend on sub-component (compound) props instead. Subset of `StylesApiProps` — no `unstyled` or `attributes`.
+
+```ts
+interface CompoundStylesApiProps<Payload extends FactoryPayload>
+  extends Omit<StylesApiProps<Payload>, 'unstyled' | 'attributes'> {}
+```
+
+Compound sub-components also use `Factory<{ ..., compound: true }>` and access styles via the parent context's `getStyles`.
+
+---
+
+## BoxProps and ElementProps
+
+**`BoxProps`** — extends `MantineStyleProps`, adds:
+```ts
+interface BoxProps extends MantineStyleProps {
+  className?: string;
+  style?: MantineStyleProp;           // accepts function: (theme) => CSSProperties
+  mod?: string | Record<string, any> | (string | Record<string, any>)[]; // data-* attributes
+  hiddenFrom?: MantineBreakpoint;     // hidden at this breakpoint and above
+  visibleFrom?: MantineBreakpoint;    // visible only at this breakpoint and above
+  lightHidden?: boolean;              // hidden in light color scheme
+  darkHidden?: boolean;               // hidden in dark color scheme
+}
+```
+
+**`MantineStyleProps`** — shorthand style props (all accept responsive `{ base, sm, md, lg, xl }` objects):
+
+| Prop | CSS property | Prop | CSS property |
+|---|---|---|---|
+| `m` `mt` `mb` `ml` `mr` `mx` `my` `ms` `me` | margin variants | `p` `pt` `pb` `pl` `pr` `px` `py` `ps` `pe` | padding variants |
+| `w` `miw` `maw` | width | `h` `mih` `mah` | height |
+| `c` | color | `bg` | background |
+| `fz` | font-size | `fw` | font-weight |
+| `ff` | font-family | `fs` | font-style |
+| `lh` | line-height | `lts` | letter-spacing |
+| `ta` | text-align | `tt` | text-transform |
+| `td` | text-decoration | `bd` | border |
+| `bdrs` | border-radius | `opacity` | opacity |
+| `pos` | position | `top` `left` `bottom` `right` `inset` | positioning |
+| `display` | display | `flex` | flex |
+
+**`ElementProps`** — gets HTML element props, remapping `style` to Mantine's type:
+```ts
+// Include all div props except style (remapped) and any conflicting props
+interface MyProps extends ElementProps<'div'> {}
+
+// Omit conflicting HTML attrs (e.g. input has native 'size' and 'color')
+interface MyProps extends ElementProps<'input', 'size' | 'color'> {
+  size?: MantineSize;
+  color?: MantineColor;
+}
+
+// Can also accept a React component type instead of element string
+interface MyProps extends ElementProps<typeof OtherComponent> {}
+```
+
+---
+
+## createSafeContext
+
+Used inside compound components to share state from the parent to sub-components.
+
+```ts
+createSafeContext<ContextValue>(
+  errorMessage: string   // thrown when hook is used outside the provider
+): [
+  Context: React.Context<ContextValue | null>,
+  useContext: () => ContextValue     // throws errorMessage if used outside provider
+]
+```
+
+**Usage pattern (in ComponentName.context.ts):**
+```ts
+import { createSafeContext, GetStylesApi } from '@mantine/core';
+import { MyFactory } from './MyComponent';
+
+interface MyContextValue {
+  getStyles: GetStylesApi<MyFactory>;
+  // other shared state...
+}
+
+export const [MyProvider, useMyContext] = createSafeContext<MyContextValue>(
+  'MyComponent was not found in tree'
+);
+```
+
+In the root component:
+```tsx
+return (
+  <MyProvider value={{ getStyles }}>
+    <Box {...getStyles('root')} {...others}>{children}</Box>
+  </MyProvider>
+);
+```
+
+In sub-components:
+```tsx
+const { getStyles } = useMyContext();
+return <div {...getStyles('item')} />;
+```
+
+---
+
+## Theme helper functions
+
+Use these in `createVarsResolver` to convert Mantine size tokens to CSS values:
+
+| Function | Input | Output example |
+|---|---|---|
+| `getSize(size, prefix)` | `'sm'`, `'button-height'` | `'var(--mantine-button-height-sm)'` |
+| `getSpacing(size)` | `'md'` or `16` | `'var(--mantine-spacing-md)'` or `'1rem'` |
+| `getRadius(size)` | `'sm'` or `4` | `'var(--mantine-radius-sm)'` or `'0.25rem'` |
+| `getFontSize(size)` | `'sm'` | `'var(--mantine-font-size-sm)'` |
+| `getLineHeight(size)` | `'sm'` | `'var(--mantine-line-height-sm)'` |
+| `getShadow(size)` | `'md'` | `'var(--mantine-shadow-md)'` |
+| `rem(value)` | `16` | `'1rem'` |
+| `em(value)` | `16` | `'1em'` |
+
+Return `undefined` from a var resolver entry to leave that CSS variable unset (CSS fallback applies).
+
+---
+
+## Static properties
+
+These must be set on every component after creation:
+
+```ts
+MyComponent.displayName = '@mantine/core/MyComponent'; // or '@mantine/package/Name'
+MyComponent.classes = classes;                          // CSS module classes object
+MyComponent.varsResolver = varsResolver;               // only if component defines vars
+
+// Sub-components (compound pattern)
+MyComponent.Item = MyItem;
+MyComponent.Label = MyLabel;
+```
+
+`.extend()` and `.withProps()` are added automatically by `factory()`.