@kpf_/kiso 1.0.0

package/README.md

@@ -0,0 +1,168 @@
+# Kiso Design System
+
+Package: `@kpf/kiso`
+Version: `1.0.0`
+Framework: React 19 / TypeScript
+
+**Kiso** (Japanese for *Foundation*) is a strict, atomic UI library built for tactile interaction and precise motion. It enforces a specific set of physics curves (`ease-kiso`) and a hardcoded token system to ensure visual consistency across applications.
+
+## Integration
+
+### 1. Installation
+
+```bash
+npm install @kpf/kiso framer-motion
+```
+
+### 2. Styles & Fonts
+
+Kiso relies on **Plus Jakarta Sans** and a compiled CSS file for token injection.
+
+In your root entry file (e.g., `main.tsx` or `layout.tsx`):
+
+```typescript
+// 1. Import the Font
+import '@fontsource/plus-jakarta-sans/400.css';
+import '@fontsource/plus-jakarta-sans/500.css';
+import '@fontsource/plus-jakarta-sans/600.css';
+import '@fontsource/plus-jakarta-sans/700.css';
+
+// 2. Import Kiso Core Styles
+import '@kpf/kiso/dist/style.css';
+```
+
+### 3. Provider Setup
+
+The system requires a global context for feedback loops (Toasts). Wrap your application root:
+
+```typescript
+import { KisoToastProvider } from '@kpf/kiso';
+
+function App() {
+  return (
+    <KisoToastProvider>
+      <YourApplication />
+    </KisoToastProvider>
+  );
+}
+```
+
+## Component Architecture
+
+Kiso uses a specific naming convention (`Kiso[Component]`) and favors **Compound Component** patterns for complex molecules to keep the API surface minimal.
+
+### Atoms
+
+#### Button
+Utilizes tactile press physics (`scale-96`) and custom easing.
+
+```typescript
+import { KisoButton } from '@kpf/kiso';
+
+<KisoButton variant='primary' onClick={handleClick}>
+  Confirm Action
+</KisoButton>
+
+<KisoButton variant='destructive' isLoading={isDeleting}>
+  Delete Item
+</KisoButton>
+```
+
+#### Input
+Includes slot support for icons and right-aligned actions.
+
+```typescript
+import { KisoInput } from '@kpf/kiso';
+import { MagnifyingGlass } from '@phosphor-icons/react';
+
+<KisoInput 
+  placeholder='Search...' 
+  leftIcon={<MagnifyingGlass />} 
+  error={hasError}
+/>
+```
+
+### Molecules (Stateful)
+
+#### Modal System
+Uses a compound pattern. The `Content` component handles the entrance animation automatically based on the `variant` prop (`standard` | `sheet` | `bottom`).
+
+```typescript
+import { KisoModal } from '@kpf/kiso';
+
+<KisoModal open={isOpen} onOpenChange={setIsOpen}>
+  <KisoModal.Content variant='sheet'>
+    <KisoModal.Header>
+      <h2>Transaction Details</h2>
+    </KisoModal.Header>
+    
+    <div className='p-6'>
+      {/* Content */}
+    </div>
+
+    <KisoModal.Footer>
+       <KisoButton variant='secondary' onClick={close}>Close</KisoButton>
+    </KisoModal.Footer>
+  </KisoModal.Content>
+</KisoModal>
+```
+
+#### Toast Feedback
+Triggered via hook.
+
+```typescript
+import { useToast } from '@kpf/kiso';
+
+const { success, error } = useToast();
+
+const handleSubmit = () => {
+  try {
+    saveData();
+    success('Changes saved successfully.');
+  } catch (err) {
+    error('Failed to save data.');
+  }
+};
+```
+
+### Motion System
+
+Kiso provides pre-configured motion primitives powered by Framer Motion. These use the **wise-drama** bezier curve (`0.1, 0.9, 0.2, 1`).
+
+#### Stagger Text
+Splits strings into characters and cascades them in.
+
+```typescript
+import { KisoStaggerText } from '@kpf/kiso';
+
+<h1 className='text-4xl font-bold text-kiso-forest'>
+  <KisoStaggerText text='Welcome Back' />
+</h1>
+```
+
+#### View Transition (Wizard)
+Handles the exit/enter overlap logic for multi-step forms.
+
+```typescript
+import { KisoViewTransition } from '@kpf/kiso';
+
+// direction is 'forward' | 'backward'
+<KisoViewTransition direction={navDirection}>
+  {step === 1 && <StepOne key='step1' />}
+  {step === 2 && <StepTwo key='step2' />}
+</KisoViewTransition>
+```
+
+## Design Tokens
+
+Do not use arbitrary values. Use the Kiso token set for consistency.
+
+| Category | Token | Value |
+| --- | --- | --- |
+| **Color** | `text-kiso-forest` | Primary Text (#163300) |
+| | `bg-kiso-green` | Primary Action (#9FE870) |
+| | `bg-kiso-gray` | Backgrounds (#F2F4F8) |
+| | `border-kiso-stroke` | Borders (#D3D5D8) |
+| **Shadow** | `shadow-kiso-modal` | Deep elevation for dialogs |
+| **Ease** | `ease-kiso` | Standard interaction curve |
+| **Ease** | `ease-drama` | Long-form motion curve |

package/dist/components/atoms/Button.d.ts

@@ -0,0 +1,11 @@
+import { VariantProps } from 'class-variance-authority';
+import * as React from "react";
+declare const buttonVariants: (props?: ({
+    variant?: "primary" | "secondary" | "destructive" | "ghost" | "inverse" | null | undefined;
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    isLoading?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export { Button, buttonVariants };

package/dist/components/atoms/Input.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+    leftIcon?: React.ReactNode;
+    rightAction?: React.ReactNode;
+    error?: boolean;
+}
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+export { Input };

package/dist/components/atoms/Toggle.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+export interface ToggleProps {
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    disabled?: boolean;
+    className?: string;
+}
+declare const Toggle: React.ForwardRefExoticComponent<ToggleProps & React.RefAttributes<HTMLButtonElement>>;
+export { Toggle };

package/dist/components/molecules/Modal.d.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+type ModalVariant = "standard" | "sheet" | "bottom";
+interface ModalContentProps extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
+    variant?: ModalVariant;
+}
+export declare const KisoModal: {
+    Root: React.FC<DialogPrimitive.DialogProps>;
+    Trigger: React.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+    Content: React.ForwardRefExoticComponent<ModalContentProps & React.RefAttributes<HTMLDivElement>>;
+    Header: {
+        ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    Footer: {
+        ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    Title: React.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogTitleProps & React.RefAttributes<HTMLHeadingElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
+    Description: React.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>, "ref"> & React.RefAttributes<HTMLParagraphElement>>;
+    Close: React.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & React.RefAttributes<HTMLButtonElement>>;
+};
+export {};

package/dist/components/molecules/Stepper.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+interface KisoStepperProps {
+    currentStep: number;
+    steps: string[];
+    className?: string;
+}
+export declare const KisoStepper: React.ForwardRefExoticComponent<KisoStepperProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/molecules/Timeline.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+interface TimelineItem {
+    id: string;
+    title: string;
+    description: string;
+    status: 'active' | 'complete' | 'pending';
+}
+interface KisoTimelineProps {
+    items: TimelineItem[];
+    className?: string;
+}
+export declare const KisoTimeline: React.ForwardRefExoticComponent<KisoTimelineProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/molecules/Toast.d.ts

@@ -0,0 +1,19 @@
+import * as React from "react";
+import * as ToastPrimitives from "@radix-ui/react-toast";
+export type KisoToastVariant = "success" | "error" | "warning" | "info";
+declare const KisoToast: React.ForwardRefExoticComponent<Omit<ToastPrimitives.ToastProps & React.RefAttributes<HTMLLIElement>, "ref"> & {
+    variant?: KisoToastVariant;
+} & React.RefAttributes<HTMLLIElement>>;
+type ToastProps = React.ComponentPropsWithoutRef<typeof KisoToast>;
+interface ToastContextType {
+    toast: (props: ToastProps & {
+        title?: string;
+        description?: string;
+        variant?: KisoToastVariant;
+    }) => void;
+}
+declare const useToast: () => ToastContextType;
+declare const KisoToaster: ({ children }: {
+    children: React.ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;
+export { KisoToast, KisoToaster, useToast };

package/dist/components/motion/HotSlider.d.ts

@@ -0,0 +1,10 @@
+interface HotSliderProps {
+    min?: number;
+    max?: number;
+    step?: number;
+    value: number;
+    onChange: (value: number) => void;
+    className?: string;
+}
+export declare function HotSlider({ min, max, step, value, onChange, className, }: HotSliderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/motion/StaggerText.d.ts

@@ -0,0 +1,6 @@
+interface StaggerTextProps {
+    text: string;
+    className?: string;
+}
+export declare function StaggerText({ text, className }: StaggerTextProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/motion/ViewTransition.d.ts

@@ -0,0 +1,8 @@
+interface KisoViewTransitionProps {
+    children: React.ReactNode;
+    direction?: "forward" | "backward";
+    className?: string;
+    layoutId?: string;
+}
+export declare function KisoViewTransition({ children, direction, className, layoutId }: KisoViewTransitionProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { Button as KisoButton, buttonVariants } from './components/atoms/Button';
+export { Input as KisoInput } from './components/atoms/Input';
+export { Toggle as KisoToggle } from './components/atoms/Toggle';
+export { KisoModal } from './components/molecules/Modal';
+export { KisoToast, KisoToaster, KisoToaster as KisoToastProvider, useToast } from './components/molecules/Toast';
+export { KisoStepper } from './components/molecules/Stepper';
+export { KisoTimeline } from './components/molecules/Timeline';
+export { StaggerText as KisoStaggerText } from './components/motion/StaggerText';
+export { HotSlider as KisoHotSlider } from './components/motion/HotSlider';
+export { KisoViewTransition } from './components/motion/ViewTransition';
+export { cn } from './lib/utils';