lkd-web-kit 0.10.6 → 0.10.8

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

@@ -1,407 +0,0 @@
-# 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()`.