pinfold 0.0.0-stage → 0.1.0

package/templates/component/react/lazy.ts.tmpl

@@ -0,0 +1,11 @@
+import { createLazyComponent } from '../lazy';
+import type { __PASCAL__Config } from './types';
+
+/** Code-split entry point: nothing loads until the component first renders. */
+export const __PASCAL__ = createLazyComponent<__PASCAL__Config>(
+  () => import('./index').then((m) => ({ default: m.__PASCAL__ })),
+  { displayName: 'Lazy__PASCAL__' },
+);
+
+export type { __PASCAL__Config } from './types';
+export default __PASCAL__;

package/templates/component/react/types.ts.tmpl

@@ -0,0 +1,142 @@
+import type * as React from 'react';
+import type {
+  PinfoldDir,
+  PinfoldOrientation,
+  PinfoldRadius,
+  PinfoldSize,
+  PinfoldTone,
+  Length,
+  PropsBag,
+} from '@pinfold/core';
+import type { PinfoldComponent } from '../component';
+import type { SlotOverrides, Slottable } from '../types';
+
+/** Name every visual part. Consumers target these by name; do not rename later. */
+export type __PASCAL__Slot = 'root' | 'item' | 'label';
+
+export type __PASCAL__Variant = 'solid' | 'outline' | 'ghost';
+
+/** Runtime state of one row. Passed to every function-valued config field. */
+export interface __PASCAL__ItemState {
+  id: string;
+  index: number;
+  selected: boolean;
+  disabled: boolean;
+  config: __PASCAL__ItemConfig;
+}
+
+/** Anything renderable: a node, or a function of the row's live state. */
+export type __PASCAL__Node = Slottable<__PASCAL__ItemState>;
+
+/** One row of data. This is the JSON a consumer — or a model — writes. */
+export interface __PASCAL__ItemConfig {
+  id?: string;
+  label: __PASCAL__Node;
+  disabled?: boolean;
+  /** Per-row class and style overrides, same slot names as the root config. */
+  classNames?: Partial<Record<__PASCAL__Slot, string>>;
+  styles?: Partial<Record<__PASCAL__Slot, React.CSSProperties>>;
+}
+
+export interface __PASCAL__BehaviourConfig {
+  items: __PASCAL__ItemConfig[];
+  value?: string | null;
+  defaultValue?: string | null;
+  onValueChange?: (value: string | null) => void;
+  orientation?: PinfoldOrientation;
+  dir?: PinfoldDir;
+  loop?: boolean;
+  /** Id prefix — set it for deterministic SSR markup. */
+  id?: string;
+}
+
+/** Numbers are px, strings pass through. Overrides the `size` preset per key. */
+export interface __PASCAL__Dimensions {
+  width?: Length;
+  maxWidth?: Length;
+  gap?: Length;
+  paddingX?: Length;
+  paddingY?: Length;
+  fontSize?: Length;
+  radius?: Length;
+  borderWidth?: Length;
+  duration?: Length;
+}
+
+export interface __PASCAL__AppearanceConfig {
+  variant?: __PASCAL__Variant;
+  size?: PinfoldSize;
+  tone?: PinfoldTone;
+  radius?: PinfoldRadius;
+  animate?: boolean;
+  dimensions?: __PASCAL__Dimensions;
+  /** Drop every Pinfold class so you can style purely with Tailwind or your own CSS. */
+  unstyled?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export interface __PASCAL__Config
+  extends __PASCAL__BehaviourConfig,
+    __PASCAL__AppearanceConfig,
+    SlotOverrides<__PASCAL__Slot, __PASCAL__ItemState> {
+  /** Replace an entire row. The last resort before dropping to prop getters. */
+  renderItem?: (args: {
+    state: __PASCAL__ItemState;
+    props: PropsBag;
+    children: React.ReactNode;
+  }) => React.ReactNode;
+}
+
+/** Appearance after provider defaults are folded in. */
+export interface Resolved__PASCAL__Appearance {
+  variant: __PASCAL__Variant;
+  size: PinfoldSize;
+  tone: PinfoldTone;
+  radius: PinfoldRadius;
+  animate: boolean;
+  unstyled: boolean;
+}
+
+/** Props accepted by the component itself, merged onto the root element. */
+export interface __PASCAL__RootProps {
+  className?: string;
+  style?: React.CSSProperties;
+  children?: never;
+  [key: `data-${string}`]: unknown;
+}
+
+/** Addressing a single row from a sub-component. */
+export interface __PASCAL__PartProps {
+  id?: string;
+  index?: number;
+  className?: string;
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+}
+
+export interface __PASCAL__State {
+  items: __PASCAL__ItemState[];
+  value: string | null;
+  select: (id: string) => void;
+  clear: () => void;
+  focusItem: (index: number) => void;
+  /** Equivalent to rendering the component, for callers who prefer a call. */
+  render: (props?: __PASCAL__RootProps) => React.ReactElement;
+  getRootProps: (props?: PropsBag) => PropsBag;
+  getItemProps: (item: __PASCAL__ItemState, props?: PropsBag) => PropsBag;
+}
+
+/** Sub-components for hand-laid-out layouts the config cannot express. */
+export interface __PASCAL__Parts {
+  Item: (props: __PASCAL__PartProps) => React.ReactElement | null;
+}
+
+/**
+ * What `use__PASCAL__()` returns: a component you render, that is also the
+ * controller, that also carries its parts.
+ */
+export type __PASCAL__Api = PinfoldComponent<
+  __PASCAL__State & __PASCAL__Parts,
+  __PASCAL__RootProps
+>;

package/templates/component/react/use__PASCAL__.tsx.tmpl

@@ -0,0 +1,181 @@
+import * as React from 'react';
+import { ariaAttr, dataAttr, mergeProps, nextIndexFromKey, warnOnce, __DEV__ } from '@pinfold/core';
+import { useControllableState, useEvent, useId } from '../hooks';
+import { usePinfold } from '../provider';
+import { usePinfoldComponent } from '../component';
+import { renderItem, renderRoot, type ViewContext } from './__PASCAL__View';
+import type {
+  Resolved__PASCAL__Appearance,
+  __PASCAL__Api,
+  __PASCAL__Config,
+  __PASCAL__ItemState,
+  __PASCAL__Parts,
+  __PASCAL__PartProps,
+  __PASCAL__RootProps,
+  __PASCAL__State,
+} from './types';
+
+/**
+ * TODO: implement the matching WAI-ARIA Authoring Practices pattern.
+ * https://www.w3.org/WAI/ARIA/apg/patterns/
+ *
+ * What ships here is the Pinfold skeleton: controllable state, roving focus, prop
+ * getters, dev diagnostics, and a hook that returns a component:
+ *
+ *   const Thing = use__PASCAL__({ items });
+ *   return <Thing className="mt-4" />;
+ *
+ * Replace the roles and keyboard map with the ones your pattern requires, then
+ * delete this comment.
+ */
+export function use__PASCAL__(config: __PASCAL__Config): __PASCAL__Api {
+  const ctx = usePinfold();
+  const {
+    items: itemConfigs,
+    value: controlled,
+    defaultValue = null,
+    onValueChange,
+    orientation = 'horizontal',
+    dir = ctx.dir,
+    loop = true,
+    id: idProp,
+  } = config;
+
+  const appearance: Resolved__PASCAL__Appearance = {
+    variant: config.variant ?? 'solid',
+    size: config.size ?? ctx.size,
+    tone: config.tone ?? ctx.tone,
+    radius: config.radius ?? ctx.radius,
+    animate: config.animate ?? !ctx.disableAnimation,
+    unstyled: config.unstyled ?? false,
+  };
+
+  const baseId = useId(idProp);
+  const refs = React.useRef<Array<HTMLElement | null>>([]);
+
+  if (__DEV__) validate(config);
+
+  const [value, setValue] = useControllableState<string | null>({
+    value: controlled,
+    defaultValue,
+    onChange: onValueChange,
+  });
+
+  const items = React.useMemo<__PASCAL__ItemState[]>(
+    () =>
+      itemConfigs.map((item, index) => {
+        const id = item.id ?? String(index);
+        return { id, index, selected: value === id, disabled: !!item.disabled, config: item };
+      }),
+    [itemConfigs, value],
+  );
+
+  const select = useEvent((id: string) => {
+    const item = items.find((i) => i.id === id);
+    if (!item || item.disabled) return;
+    setValue(id);
+  });
+
+  const focusItem = useEvent((index: number) => refs.current[index]?.focus());
+
+  const onKeyDown = useEvent((event: React.KeyboardEvent, index: number) => {
+    const next = nextIndexFromKey(event.key, index, items.length, { orientation, dir, loop });
+    if (next === null) return;
+    event.preventDefault();
+    focusItem(next);
+  });
+
+  // Rendering reads through this ref so the returned component keeps a stable
+  // identity while always seeing the current config and state.
+  const viewRef = React.useRef<ViewContext>(null as unknown as ViewContext);
+
+  const state: __PASCAL__State = {
+    items,
+    value,
+    select,
+    clear: useEvent(() => setValue(null)),
+    focusItem,
+    render: (props?: __PASCAL__RootProps) => renderRoot(viewRef.current, props),
+
+    getRootProps: (props) =>
+      mergeProps({ 'data-pinfold': '__NAME__', 'data-orientation': orientation, dir }, props),
+
+    getItemProps: (item, props) =>
+      mergeProps(
+        {
+          type: 'button',
+          id: `${baseId}-item-${item.id}`,
+          'aria-disabled': ariaAttr(item.disabled),
+          'data-state': item.selected ? 'selected' : 'idle',
+          'data-disabled': dataAttr(item.disabled),
+          'data-index': item.index,
+          ref: (node: HTMLElement | null) => {
+            refs.current[item.index] = node;
+          },
+          onClick: (event: React.MouseEvent) => {
+            if (item.disabled) {
+              event.preventDefault();
+              return;
+            }
+            api.select(item.id);
+          },
+          onKeyDown: (event: React.KeyboardEvent) => onKeyDown(event, item.index),
+        },
+        props,
+      ),
+  };
+
+  // Built once (inside usePinfoldComponent): a fresh identity each render would
+  // make React tear down and rebuild the subtree on every parent update.
+  const buildParts = () => {
+    const pick = (props: __PASCAL__PartProps): __PASCAL__ItemState | undefined => {
+      const rows = viewRef.current.api.items;
+      return props.index != null
+        ? rows[props.index]
+        : props.id != null
+          ? rows.find((row) => row.id === props.id)
+          : rows[0];
+    };
+
+    return {
+      Item: (props: __PASCAL__PartProps) => {
+        const item = pick(props);
+        return item
+          ? renderItem(viewRef.current, item, { className: props.className, style: props.style })
+          : null;
+      },
+    };
+  };
+
+  const api = usePinfoldComponent<__PASCAL__State, __PASCAL__RootProps, __PASCAL__Parts>(
+    '__PASCAL__',
+    state,
+    (props) => renderRoot(viewRef.current, props),
+    buildParts,
+  );
+
+  viewRef.current = { api, config, a: appearance };
+
+  return api;
+}
+
+/** Dev-only checks for mistakes that would otherwise show up as odd behaviour. */
+function validate(config: __PASCAL__Config): void {
+  const { items, value, onValueChange } = config;
+
+  warnOnce(!Array.isArray(items), '__PASCAL__: `items` must be an array.');
+  if (!Array.isArray(items)) return;
+
+  const ids = items.map((item, i) => item.id ?? String(i));
+  const duplicate = ids.find((id, i) => ids.indexOf(id) !== i);
+  warnOnce(
+    duplicate !== undefined,
+    `__PASCAL__: duplicate item id ${JSON.stringify(duplicate)}. Ids must be unique.`,
+  );
+
+  warnOnce(
+    value !== undefined && onValueChange === undefined,
+    '__PASCAL__: `value` was passed without `onValueChange`, so it is frozen. ' +
+      'Use `defaultValue` for uncontrolled behaviour.',
+  );
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.