what-framework 0.1.0

package/index.d.ts

@@ -0,0 +1,252 @@
+// What Framework - TypeScript Definitions
+
+// --- Reactive Primitives ---
+
+/** A reactive value container */
+export interface Signal<T> {
+  /** Read the current value (tracks dependency if inside effect) */
+  (): T;
+  /** Update the value */
+  set(value: T | ((prev: T) => T)): void;
+  /** Read without tracking */
+  peek(): T;
+  /** Subscribe to changes */
+  subscribe(fn: (value: T) => void): () => void;
+  /** Internal marker */
+  _signal: true;
+}
+
+/** Create a reactive signal */
+export function signal<T>(initial: T): Signal<T>;
+
+/** A derived reactive value (lazy evaluation) */
+export interface Computed<T> {
+  (): T;
+  peek(): T;
+  _signal: true;
+}
+
+/** Create a computed signal */
+export function computed<T>(fn: () => T): Computed<T>;
+
+/** Create a side effect that re-runs when dependencies change */
+export function effect(fn: () => void | (() => void)): () => void;
+
+/** Batch multiple signal updates into one flush */
+export function batch<T>(fn: () => T): T;
+
+/** Read signals without subscribing */
+export function untrack<T>(fn: () => T): T;
+
+// --- Virtual DOM ---
+
+export interface VNode<P = any> {
+  tag: string | Component<P>;
+  props: P;
+  children: VNodeChild[];
+  key: string | number | null;
+  _vnode: true;
+}
+
+export type VNodeChild = VNode | string | number | boolean | null | undefined | VNodeChild[];
+
+export type Component<P = {}> = (props: P & { children?: VNodeChild }) => VNode | VNodeChild;
+
+/** Create a virtual DOM node */
+export function h<P extends {}>(
+  tag: string | Component<P>,
+  props?: P | null,
+  ...children: VNodeChild[]
+): VNode<P>;
+
+/** Fragment component */
+export function Fragment(props: { children?: VNodeChild }): VNodeChild;
+
+/** Tagged template for JSX-like syntax without build step */
+export function html(strings: TemplateStringsArray, ...values: any[]): VNode | VNode[];
+
+// --- DOM Mounting ---
+
+/** Mount a VNode tree into a container */
+export function mount(vnode: VNode, container: string | Element): () => void;
+
+// --- Hooks ---
+
+/** State hook - returns [value, setter] */
+export function useState<T>(initial: T | (() => T)): [T, (value: T | ((prev: T) => T)) => void];
+
+/** Signal hook - returns raw signal */
+export function useSignal<T>(initial: T | (() => T)): Signal<T>;
+
+/** Computed hook */
+export function useComputed<T>(fn: () => T): Computed<T>;
+
+/** Effect hook with optional dependencies */
+export function useEffect(fn: () => void | (() => void), deps?: any[]): void;
+
+/** Memoized value hook */
+export function useMemo<T>(fn: () => T, deps: any[]): T;
+
+/** Memoized callback hook */
+export function useCallback<T extends (...args: any[]) => any>(fn: T, deps: any[]): T;
+
+/** Ref hook */
+export function useRef<T>(initial: T): { current: T };
+
+/** Context hook */
+export function useContext<T>(context: Context<T>): T;
+
+/** Reducer hook */
+export function useReducer<S, A>(
+  reducer: (state: S, action: A) => S,
+  initialState: S,
+  init?: (initial: S) => S
+): [S, (action: A) => void];
+
+/** Create a context */
+export interface Context<T> {
+  _value: T;
+  Provider: Component<{ value: T; children?: VNodeChild }>;
+}
+
+export function createContext<T>(defaultValue: T): Context<T>;
+
+// --- Component Utilities ---
+
+/** Skip re-render if props are equal */
+export function memo<P>(
+  component: Component<P>,
+  areEqual?: (prev: P, next: P) => boolean
+): Component<P>;
+
+/** Lazy-load a component */
+export function lazy<P>(
+  loader: () => Promise<{ default: Component<P> } | Component<P>>
+): Component<P>;
+
+/** Suspense boundary for lazy components */
+export function Suspense(props: {
+  fallback: VNodeChild;
+  children?: VNodeChild;
+}): VNode;
+
+/** Error boundary for catching component errors */
+export function ErrorBoundary(props: {
+  fallback: VNodeChild | ((props: { error: Error; reset: () => void }) => VNodeChild);
+  onError?: (error: Error) => void;
+  children?: VNodeChild;
+}): VNode;
+
+// --- Store ---
+
+export interface StoreDefinition {
+  [key: string]: any;
+}
+
+export type Store<T extends StoreDefinition> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any ? T[K] : T[K];
+};
+
+/** Create a global reactive store */
+export function createStore<T extends StoreDefinition>(definition: T): () => Store<T>;
+
+/** Create a simple global atom */
+export function atom<T>(initial: T): Signal<T>;
+
+// --- Utilities ---
+
+/** Conditional rendering helper */
+export function show<T extends VNodeChild>(condition: boolean, vnode: T, fallback?: VNodeChild): T | VNodeChild;
+
+/** List rendering helper with optional key function */
+export function each<T>(
+  list: T[],
+  fn: (item: T, index: number) => VNode,
+  keyFn?: (item: T, index: number) => string | number
+): VNode[];
+
+/** Conditional class names */
+export function cls(...args: (string | false | null | undefined | Record<string, boolean>)[]): string;
+
+/** Convert style object to string */
+export function style(obj: string | Record<string, string | number | null | undefined>): string;
+
+/** Debounce a function */
+export function debounce<T extends (...args: any[]) => any>(fn: T, ms: number): T;
+
+/** Throttle a function */
+export function throttle<T extends (...args: any[]) => any>(fn: T, ms: number): T;
+
+/** Reactive media query */
+export function useMediaQuery(query: string): Signal<boolean>;
+
+/** Signal synced with localStorage */
+export function useLocalStorage<T>(key: string, initial: T): Signal<T>;
+
+/** Render children in a different DOM container */
+export function Portal(props: { target: string | Element; children?: VNodeChild }): VNode | null;
+
+/** CSS transition helper */
+export function transition(name: string, active: boolean): { class: string };
+
+// --- Head Management ---
+
+/** Manage document head */
+export function Head(props: {
+  title?: string;
+  meta?: Record<string, string>[];
+  link?: Record<string, string>[];
+  script?: Record<string, string>[];
+  children?: VNodeChild;
+}): null;
+
+/** Clear managed head elements */
+export function clearHead(): void;
+
+// --- DOM Scheduler ---
+
+/** Schedule a DOM read operation */
+export function scheduleRead(fn: () => void): () => void;
+
+/** Schedule a DOM write operation */
+export function scheduleWrite(fn: () => void): () => void;
+
+/** Flush all pending scheduler operations */
+export function flushScheduler(): void;
+
+/** Measure DOM (returns promise) */
+export function measure<T>(fn: () => T): Promise<T>;
+
+/** Mutate DOM (returns promise) */
+export function mutate(fn: () => void): Promise<void>;
+
+/** Effect that batches DOM operations */
+export function useScheduledEffect(
+  readFn: () => any,
+  writeFn?: (data: any) => void
+): () => void;
+
+/** Returns promise that resolves on next animation frame */
+export function nextFrame(): Promise<void> & { cancel: () => void };
+
+/** Debounced requestAnimationFrame */
+export function raf(key: string, fn: () => void): void;
+
+/** Observe element resize */
+export function onResize(
+  element: Element,
+  callback: (rect: DOMRectReadOnly) => void
+): () => void;
+
+/** Observe element intersection */
+export function onIntersect(
+  element: Element,
+  callback: (entry: IntersectionObserverEntry) => void,
+  options?: IntersectionObserverInit
+): () => void;
+
+/** Smooth scroll to element */
+export function smoothScrollTo(
+  element: Element,
+  options?: { duration?: number; easing?: (t: number) => number }
+): Promise<void>;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "what-framework",
+  "version": "0.1.0",
+  "description": "The closest framework to vanilla JS — signals, components, islands, SSR",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./router": {
+      "types": "./router.d.ts",
+      "import": "./src/router.js"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "import": "./src/server.js"
+    },
+    "./testing": {
+      "types": "./testing.d.ts",
+      "import": "./src/testing.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "router.d.ts",
+    "server.d.ts",
+    "testing.d.ts"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "framework",
+    "signals",
+    "reactive",
+    "islands",
+    "ssr",
+    "vanilla-js",
+    "lightweight",
+    "router",
+    "components"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aspect/what-fw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aspect/what-fw/issues"
+  },
+  "homepage": "https://github.com/aspect/what-fw#readme"
+}

package/router.d.ts

@@ -0,0 +1,128 @@
+// What Framework Router - TypeScript Definitions
+
+import { VNode, VNodeChild, Component, Signal, Computed } from './index';
+
+// --- Route State ---
+
+export interface RouteState {
+  /** Current full URL */
+  readonly url: string;
+  /** Current pathname */
+  readonly path: string;
+  /** Route parameters */
+  readonly params: Record<string, string>;
+  /** Query parameters */
+  readonly query: Record<string, string>;
+  /** URL hash */
+  readonly hash: string;
+  /** Navigation in progress */
+  readonly isNavigating: boolean;
+  /** Navigation error if any */
+  readonly error: Error | null;
+}
+
+export const route: RouteState;
+
+// --- Navigation ---
+
+export interface NavigateOptions {
+  /** Replace current history entry */
+  replace?: boolean;
+  /** History state object */
+  state?: any;
+  /** Use View Transitions API */
+  transition?: boolean;
+}
+
+/** Navigate to a new URL */
+export function navigate(to: string, options?: NavigateOptions): Promise<void>;
+
+/** Redirect (throws to navigate) */
+export function redirect(to: string, options?: NavigateOptions): never;
+
+// --- Route Configuration ---
+
+export interface RouteConfig {
+  /** URL path pattern */
+  path: string;
+  /** Page component */
+  component: Component<RouteComponentProps>;
+  /** Layout wrapper */
+  layout?: Component<LayoutProps>;
+  /** Loading component */
+  loading?: Component<{}>;
+  /** Error component */
+  error?: Component<{ error: Error }>;
+  /** Route middleware */
+  middleware?: RouteMiddleware[];
+}
+
+export interface RouteComponentProps {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  route: RouteConfig;
+}
+
+export interface LayoutProps {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  children?: VNodeChild;
+}
+
+export type RouteMiddleware = (props: RouteComponentProps) => boolean | Promise<boolean>;
+
+// --- Router Component ---
+
+export interface RouterProps {
+  routes: RouteConfig[];
+  fallback?: Component<{}>;
+  globalLayout?: Component<{ children?: VNodeChild }>;
+}
+
+export function Router(props: RouterProps): VNode;
+
+// --- Link Component ---
+
+export interface LinkProps {
+  href: string;
+  class?: string;
+  className?: string;
+  replace?: boolean;
+  prefetch?: boolean;
+  activeClass?: string;
+  exactActiveClass?: string;
+  transition?: boolean;
+  children?: VNodeChild;
+  [key: string]: any;
+}
+
+export function Link(props: LinkProps): VNode;
+export function NavLink(props: LinkProps): VNode;
+
+// --- Route Helpers ---
+
+/** Define routes from object config */
+export function defineRoutes(config: Record<string, Component | Partial<RouteConfig>>): RouteConfig[];
+
+// --- Prefetch ---
+
+export function prefetchRoute(href: string): void;
+
+// --- Navigation Hooks ---
+
+export function beforeNavigate(fn: (to: string, from: string) => boolean | Promise<boolean>): () => void;
+export function afterNavigate(fn: (to: string, from: string) => void): () => void;
+
+// --- useRoute Hooks ---
+
+export function useRoute(): {
+  path: Computed<string>;
+  params: Computed<Record<string, string>>;
+  query: Computed<Record<string, string>>;
+  hash: Computed<string>;
+  isNavigating: Computed<boolean>;
+};
+
+export function useParams<T extends Record<string, string> = Record<string, string>>(): T;
+export function useSearch<T extends Record<string, string> = Record<string, string>>(): T;
+export function useNavigate(): typeof navigate;

package/server.d.ts

@@ -0,0 +1,113 @@
+// What Framework Server - TypeScript Definitions
+
+import { VNode, VNodeChild, Signal } from './index';
+
+// --- SSR ---
+
+/** Render VNode tree to HTML string */
+export function renderToString(vnode: VNode): string;
+
+/** Render VNode tree as async iterator for streaming */
+export function renderToStream(vnode: VNode): AsyncGenerator<string>;
+
+/** Render a full page with document wrapper */
+export function renderPage(vnode: VNode, options?: {
+  title?: string;
+  meta?: Record<string, string>;
+  scripts?: string[];
+  styles?: string[];
+  mode?: 'static' | 'server' | 'client' | 'hybrid';
+}): string;
+
+// --- Page Configuration ---
+
+export interface PageConfig {
+  /** Rendering mode */
+  mode?: 'static' | 'server' | 'client' | 'hybrid';
+  /** Page title */
+  title?: string;
+  /** Meta tags */
+  meta?: Record<string, string>;
+  /** Page component */
+  component: (data?: any) => VNode;
+  /** Islands to hydrate */
+  islands?: string[];
+  /** Scripts to load */
+  scripts?: string[];
+  /** Stylesheets to load */
+  styles?: string[];
+}
+
+export function definePage(config: Partial<PageConfig>): PageConfig;
+
+// --- Islands ---
+
+export type IslandMode = 'static' | 'idle' | 'visible' | 'load' | 'media' | 'action';
+
+export const IslandModes: {
+  STATIC: 'static';
+  IDLE: 'idle';
+  VISIBLE: 'visible';
+  LOAD: 'load';
+  MEDIA: 'media';
+  ACTION: 'action';
+};
+
+export interface IslandOptions {
+  /** Hydration mode */
+  mode?: IslandMode;
+  /** Media query for 'media' mode */
+  media?: string;
+  /** Priority (higher = hydrate first) */
+  priority?: number;
+  /** Shared stores this island uses */
+  stores?: string[];
+}
+
+/** Register an island component */
+export function island(
+  name: string,
+  loader: () => Promise<any>,
+  options?: IslandOptions
+): void;
+
+/** Island component wrapper for SSR */
+export function Island(props: {
+  name: string;
+  props?: Record<string, any>;
+  mode?: IslandMode;
+  priority?: number;
+  stores?: string[];
+  children?: VNodeChild;
+}): VNode;
+
+/** Hydrate all islands on the page */
+export function hydrateIslands(): void;
+
+// --- Server Actions ---
+
+export interface ActionOptions {
+  id?: string;
+  onError?: (error: Error) => void;
+  onSuccess?: (result: any) => void;
+  revalidate?: string[];
+}
+
+/** Create a server action */
+export function createAction<T extends any[], R>(
+  fn: (...args: T) => Promise<R>,
+  options?: ActionOptions
+): (...args: T) => Promise<R>;
+
+/** Hook for using server actions */
+export interface UseActionResult<T extends any[], R> {
+  trigger: (...args: T) => Promise<R>;
+  isPending: () => boolean;
+  error: () => Error | null;
+  data: () => R | null;
+  reset: () => void;
+}
+
+export function useAction<T extends any[], R>(
+  actionFn: (...args: T) => Promise<R>
+): UseActionResult<T, R>;

package/src/index.js

@@ -0,0 +1,144 @@
+// What Framework - The closest framework to vanilla JS
+// Main entry point - exports everything from core
+
+// Reactivity
+export {
+  signal,
+  computed,
+  effect,
+  batch,
+  untrack,
+} from '../../core/src/reactive.js';
+
+// Virtual DOM
+export {
+  h,
+  Fragment,
+  jsx,
+  jsxs,
+  jsxDEV,
+} from '../../core/src/h.js';
+
+// DOM operations
+export {
+  mount,
+  hydrate,
+  render,
+  createPortal,
+} from '../../core/src/dom.js';
+
+// Hooks
+export {
+  useState,
+  useSignal,
+  useEffect,
+  useMemo,
+  useCallback,
+  useRef,
+  useReducer,
+  useContext,
+  createContext,
+} from '../../core/src/hooks.js';
+
+// Components
+export {
+  lazy,
+  Suspense,
+  ErrorBoundary,
+} from '../../core/src/components.js';
+
+// Store
+export {
+  createStore,
+} from '../../core/src/store.js';
+
+// Helpers
+export {
+  show,
+  each,
+  cls,
+  createPersisted,
+} from '../../core/src/helpers.js';
+
+// Head management
+export {
+  Head,
+  useHead,
+} from '../../core/src/head.js';
+
+// Animation
+export {
+  spring,
+  tween,
+  easings,
+  useGesture,
+  createTransitionClasses,
+} from '../../core/src/animation.js';
+
+// Accessibility
+export {
+  useFocusTrap,
+  useAriaLive,
+  announce,
+  clearAnnouncements,
+  useId,
+  useIds,
+  ariaLive,
+  Keys,
+  onKey,
+  onKeys,
+  trapFocus,
+  releaseFocus,
+  getFocusableElements,
+  getFirstFocusable,
+  getLastFocusable,
+  focusFirst,
+  focusLast,
+  wrapFocus,
+} from '../../core/src/a11y.js';
+
+// Skeleton loaders
+export {
+  Skeleton,
+  SkeletonText,
+  SkeletonCircle,
+  SkeletonCard,
+  SkeletonAvatar,
+  SkeletonButton,
+  SkeletonInput,
+  SkeletonImage,
+  Spinner,
+} from '../../core/src/skeleton.js';
+
+// Data fetching
+export {
+  useFetch,
+  useSWR,
+  useQuery,
+  useInfiniteQuery,
+  useMutation,
+  cache,
+  prefetch,
+} from '../../core/src/data.js';
+
+// Forms
+export {
+  useForm,
+  useField,
+  useFieldArray,
+  rules,
+  simpleResolver,
+  zodResolver,
+  yupResolver,
+} from '../../core/src/form.js';
+
+// Scheduler
+export {
+  raf,
+  cancelRaf,
+  onIdle,
+  cancelIdle,
+  nextTick,
+  scheduleTask,
+  TaskPriority,
+} from '../../core/src/scheduler.js';

package/src/router.js

@@ -0,0 +1,18 @@
+// What Framework - Router
+// Re-exports from router package
+
+export {
+  Router,
+  Link,
+  NavLink,
+  navigate,
+  redirect,
+  useRoute,
+  useParams,
+  useSearch,
+  useNavigate,
+  defineRoutes,
+  prefetchRoute,
+  beforeNavigate,
+  afterNavigate,
+} from '../../router/src/index.js';

package/src/server.js

@@ -0,0 +1,21 @@
+// What Framework - Server
+// Re-exports from server package (SSR, islands, streaming)
+
+export {
+  renderToString,
+  renderToStream,
+  renderPage,
+  definePage,
+} from '../../server/src/index.js';
+
+export {
+  island,
+  Island,
+  hydrateIslands,
+  IslandModes,
+} from '../../server/src/islands.js';
+
+export {
+  createAction,
+  useAction,
+} from '../../server/src/actions.js';

package/src/testing.js

@@ -0,0 +1,4 @@
+// What Framework - Testing utilities
+// Re-exports from core testing module
+
+export * from '../../core/src/testing.js';

package/testing.d.ts

@@ -0,0 +1,103 @@
+// What Framework - Testing Utilities Type Definitions
+
+import { VNode, Signal } from './index';
+
+// Setup and Cleanup
+export function setupDOM(): HTMLElement | null;
+export function cleanup(): void;
+
+// Render
+export interface RenderResult {
+  container: HTMLElement;
+  unmount: () => void;
+  getByText: (text: string | RegExp) => HTMLElement | null;
+  getByTestId: (id: string) => HTMLElement | null;
+  getByRole: (role: string) => HTMLElement | null;
+  getAllByText: (text: string | RegExp) => HTMLElement[];
+  queryByText: (text: string | RegExp) => HTMLElement | null;
+  queryByTestId: (id: string) => HTMLElement | null;
+  debug: () => void;
+  findByText: (text: string | RegExp, timeout?: number) => Promise<HTMLElement>;
+  findByTestId: (id: string, timeout?: number) => Promise<HTMLElement>;
+}
+
+export interface RenderOptions {
+  container?: HTMLElement;
+}
+
+export function render(vnode: VNode, options?: RenderOptions): RenderResult;
+
+// Fire Events
+export interface FireEvent {
+  click(element: HTMLElement): MouseEvent;
+  change(element: HTMLInputElement, value: string): Event;
+  input(element: HTMLInputElement, value: string): Event;
+  submit(element: HTMLFormElement): Event;
+  focus(element: HTMLElement): FocusEvent;
+  blur(element: HTMLElement): FocusEvent;
+  keyDown(element: HTMLElement, key: string, options?: KeyboardEventInit): KeyboardEvent;
+  keyUp(element: HTMLElement, key: string, options?: KeyboardEventInit): KeyboardEvent;
+  mouseEnter(element: HTMLElement): MouseEvent;
+  mouseLeave(element: HTMLElement): MouseEvent;
+}
+
+export const fireEvent: FireEvent;
+
+// Wait Utilities
+export interface WaitOptions {
+  timeout?: number;
+  interval?: number;
+}
+
+export function waitFor<T>(callback: () => T, options?: WaitOptions): Promise<T>;
+export function waitForElementToBeRemoved(callback: () => HTMLElement | null, options?: WaitOptions): Promise<void>;
+
+// Act
+export function act<T>(callback: () => T | Promise<T>): Promise<T>;
+
+// Signal Testing Helpers
+export interface TestSignal<T> {
+  signal: Signal<T>;
+  value: T;
+  history: T[];
+  reset(): void;
+}
+
+export function createTestSignal<T>(initial: T): TestSignal<T>;
+
+// Mocking
+export interface MockComponent {
+  (props: Record<string, any>): VNode;
+  displayName: string;
+  calls: Array<{ props: Record<string, any>; timestamp: number }>;
+  lastCall(): { props: Record<string, any>; timestamp: number } | undefined;
+  reset(): void;
+}
+
+export function mockComponent(name?: string): MockComponent;
+
+// Assertions
+export interface Expect {
+  toBeInTheDocument(element: HTMLElement | null): void;
+  toHaveTextContent(element: HTMLElement | null, text: string | RegExp): void;
+  toHaveAttribute(element: HTMLElement | null, attr: string, value?: string): void;
+  toHaveClass(element: HTMLElement | null, className: string): void;
+  toBeVisible(element: HTMLElement | null): void;
+  toBeDisabled(element: HTMLElement | null): void;
+  toHaveValue(element: HTMLInputElement | null, value: string): void;
+}
+
+export const expect: Expect;
+
+// Screen
+export interface Screen {
+  getByText(text: string | RegExp): HTMLElement | null;
+  getByTestId(id: string): HTMLElement | null;
+  getByRole(role: string): HTMLElement | null;
+  getAllByText(text: string | RegExp): HTMLElement[];
+  queryByText(text: string | RegExp): HTMLElement | null;
+  queryByTestId(id: string): HTMLElement | null;
+  debug(): void;
+}
+
+export const screen: Screen;