pinfold 0.0.1 → 0.2.0

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

@@ -0,0 +1,22 @@
+/* Styles ship separately so SSR and CJS never choke on a CSS import:
+     import '@pinfold/css/core.css'; import '@pinfold/css/__NAME__.css';
+   `npx pinfold add __NAME__` wires this up for you. */
+
+export { __PASCAL__ } from './__PASCAL__';
+export { use__PASCAL__ } from './use__PASCAL__';
+export type {
+  __PASCAL__Config,
+  __PASCAL__Api,
+  __PASCAL__Dimensions,
+  __PASCAL__ItemConfig,
+  __PASCAL__ItemState,
+  __PASCAL__Slot,
+  __PASCAL__Variant,
+  __PASCAL__State,
+  __PASCAL__Parts,
+  __PASCAL__PartProps,
+  __PASCAL__RootProps,
+  __PASCAL__Node,
+} from './types';
+
+export { __PASCAL__ as default } from './__PASCAL__';

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/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Indranil Bhattacharya
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,6 +0,0 @@
-# pinfold
-
-The CLI for [Pinfold](https://github.com/IndranilBhattacharya/pinfold), a hooks-first, config-driven
-React UI library by Indranil Bhattacharya.
-
-Pre-release placeholder. The real CLI (`npx pinfold init`, `add`, `theme`, `doctor`) ships as 0.1.0.

package/bin/pinfold.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log('Pinfold is in pre-release. Follow https://github.com/IndranilBhattacharya/pinfold for the first version.');