@textui/core 0.1.0

package/src/types/render.ts

@@ -0,0 +1,86 @@
+import type { Rect, Size } from './geometry.js';
+import type { Cell, Color } from './cells.js';
+import type { Attrs } from './cells.js';
+import type { Style } from './style.js';
+import type { ResolvedTheme } from './theme.js';
+import type { TerminalCapabilities } from './capabilities.js';
+import type { ComponentNode } from './graph.js';
+
+/** What a host component paints onto. Clipped to the node's own rect. */
+export interface PaintSurface {
+  readonly rect: Rect;
+  /** Write a grapheme at a content-relative cell. Out of bounds is a no-op. */
+  put(x: number, y: number, char: string, style?: CellStyle): void;
+  /** Write a string, advancing by grapheme width. Returns cells consumed. */
+  text(x: number, y: number, text: string, style?: CellStyle): number;
+  fill(rect: Rect | undefined, char: string, style?: CellStyle): void;
+  /** Direct cell write, for painters that already resolved everything. */
+  cell(x: number, y: number, cell: Cell): void;
+  /** A sub-surface, clipped and offset. */
+  clip(rect: Rect): PaintSurface;
+}
+
+export interface CellStyle {
+  fg?: Color;
+  bg?: Color;
+  attrs?: Attrs;
+  link?: string;
+}
+
+/** Everything a host needs that is not its props. */
+export interface RenderContext {
+  theme: ResolvedTheme;
+  capabilities: TerminalCapabilities;
+  /** Interaction state, already resolved for this instance. */
+  focused: boolean;
+  hovered: boolean;
+  active: boolean;
+  selected: boolean;
+  disabled: boolean;
+  /** Resolve a style token or literal to a concrete colour. */
+  color(c: unknown, fallback?: Color): Color;
+  /** Glyph for a role, downgraded to ascii when the terminal demands it. */
+  glyph(name: string): string;
+  /** Measure a string in terminal cells, honouring wide and zero-width. */
+  measureText(text: string): number;
+}
+
+export interface MeasureConstraints {
+  /** Infinity means "as much as you want". */
+  maxWidth: number;
+  maxHeight: number;
+  minWidth: number;
+  minHeight: number;
+}
+
+/**
+ * A host component is a primitive that participates in layout and paint
+ * directly. There are deliberately few of them - Box, Text and Canvas - and
+ * the entire catalog is function components composing those, so the layout
+ * engine only ever reasons about three shapes.
+ */
+export interface HostComponent<P = Record<string, unknown>> {
+  name: string;
+  /** Style contributed by props, merged under the node's own `style` prop. */
+  style?(props: P, ctx: RenderContext): Style | undefined;
+  /** Intrinsic size when the style does not fix one. */
+  measure?(props: P, ctx: RenderContext, constraints: MeasureConstraints): Size;
+  /** Paint the content box. Border and background are painted by the runtime. */
+  paint?(surface: PaintSurface, props: P, ctx: RenderContext): void;
+  /** True when this host lays out children (Box). */
+  container?: boolean;
+  /** Never receives children; a children prop is a programmer error. */
+  leaf?: boolean;
+}
+
+export type FunctionComponent<P = any> = (props: P) => RenderOutput;
+
+export type RenderOutput =
+  | ComponentNode
+  | ComponentNode[]
+  | string
+  | number
+  | null
+  | undefined
+  | false
+  | RenderOutput[];

package/src/types/resource.ts

@@ -0,0 +1,185 @@
+import type { Disposable } from './disposable.js';
+import type { ComponentNode } from './graph.js';
+import type { WhenClause } from './when.js';
+import type { CommandHandler } from './command.js';
+import type { SemanticVariant } from './style.js';
+
+/**
+ * A resource is anything addressable that a viewer, an editor or an action can
+ * be registered for - a file, a record, a log stream, a service, a chart
+ * source. The filesystem is one provider among several, not the model.
+ */
+export type ResourceURI = string;
+
+export interface ResourceKind {
+  /** Stable id: 'file.markdown', 'service', 'log.stream'. */
+  id: string;
+  title: string;
+  icon?: string;
+  /**
+   * What colour the icon is, as a role rather than a colour.
+   *
+   * Named the way every other tone in the library is, so a kind picks
+   * "informational" and the theme decides what that looks like - a kind
+   * carrying `#d19a66` would be a kind that looks wrong in half the themes.
+   */
+  tone?: SemanticVariant;
+  /** MIME types this kind claims. */
+  mimeTypes?: string[];
+  /** Filename globs this kind claims. */
+  extensions?: string[];
+  /** Kinds this one specialises. `file.markdown` extends `file.text`. */
+  extends?: string;
+  /** Higher wins when several kinds match. */
+  priority?: number;
+  /** Last word on ambiguous matches. */
+  detect?(uri: ResourceURI, meta: ResourceMetadata): boolean;
+}
+
+export interface ResourceMetadata {
+  name: string;
+  size?: number;
+  modified?: number;
+  created?: number;
+  mimeType?: string;
+  readonly?: boolean;
+  /** Provider-specific extras. */
+  [key: string]: unknown;
+}
+
+/**
+ * What a *resource* can have done to it - not what its provider implements.
+ *
+ * Per resource on purpose: a read-only mount, a file the user has no
+ * permission on, and something inherently immutable all come back the same
+ * shape, and a caller deciding whether to offer Delete should never have to
+ * know which of the three it is looking at.
+ *
+ * This is what to ask before calling; the registry method still throws if the
+ * answer changed in between. `stream` is the odd one - declarative only, no
+ * registry method reads it. It stays for a log provider to claim, and comes
+ * out if none does.
+ */
+export type ResourceCapability =
+  | 'read' | 'write' | 'delete' | 'rename' | 'list' | 'watch' | 'stream';
+
+export interface Resource {
+  uri: ResourceURI;
+  kind: string;
+  metadata: ResourceMetadata;
+  capabilities: ResourceCapability[];
+}
+
+/** Where resources come from. One per URI scheme. */
+export interface ResourceProvider {
+  scheme: string;
+  stat(uri: ResourceURI): Promise<Resource | null>;
+  list?(uri: ResourceURI): Promise<Resource[]>;
+  read?(uri: ResourceURI): Promise<string | Uint8Array>;
+  write?(uri: ResourceURI, content: string | Uint8Array): Promise<void>;
+  delete?(uri: ResourceURI): Promise<void>;
+  rename?(from: ResourceURI, to: ResourceURI): Promise<void>;
+  watch?(uri: ResourceURI, fn: (event: 'change' | 'create' | 'delete') => void): Disposable;
+}
+
+/** A component that can display one kind of resource. */
+export interface ResourceViewerDefinition {
+  id: string;
+  title: string;
+  kinds: string[];
+  /** Component name; receives `{ resource, content }`. */
+  component: string;
+  icon?: string;
+  /** As on a kind. A renderer that declares one speaks for what it opens. */
+  tone?: SemanticVariant;
+  priority?: number;
+  when?: WhenClause;
+  /** Accept anything no specific viewer claims. */
+  fallback?: boolean;
+}
+
+export interface ResourceEditorDefinition extends ResourceViewerDefinition {
+  /** Editors must be able to hand back new content. */
+  saves: true;
+}
+
+export interface ResourceActionDefinition {
+  id: string;
+  title: string;
+  kinds: string[];
+  icon?: string;
+  when?: WhenClause;
+  /** Where the action offers itself: 'context', 'toolbar', 'palette'. */
+  slots?: string[];
+  priority?: number;
+  run: CommandHandler;
+}
+
+export interface ResourceRegistry {
+  registerKind(kind: ResourceKind): Disposable;
+  registerProvider(provider: ResourceProvider): Disposable;
+  registerViewer(def: ResourceViewerDefinition): Disposable;
+  registerEditor(def: ResourceEditorDefinition): Disposable;
+  registerAction(def: ResourceActionDefinition): Disposable;
+
+  kinds(): ResourceKind[];
+  /** Classify a resource: extension, then mime, then `detect`, then parent. */
+  detectKind(uri: ResourceURI, meta?: ResourceMetadata): string;
+  /** True when `kind` is `ancestor` or specialises it. */
+  kindMatches(kind: string, ancestor: string): boolean;
+
+  // The registry forwards every operation a provider can offer, so a caller
+  // never needs to reach past it to a provider - there is no public path to
+  // one, and a caller that found one would be hardcoding a scheme.
+  //
+  // `list` and `watch` answer emptily when the provider cannot serve them;
+  // `read`, `write`, `delete` and `rename` throw. The split is intent: an
+  // absent listing is a fact about the resource, and an absent delete is a
+  // request that did not happen and must say so.
+  stat(uri: ResourceURI): Promise<Resource | null>;
+  list(uri: ResourceURI): Promise<Resource[]>;
+  read(uri: ResourceURI): Promise<string | Uint8Array>;
+  write(uri: ResourceURI, content: string | Uint8Array): Promise<void>;
+  /** Throws when the provider cannot. Ask `Resource.capabilities` first. */
+  delete(uri: ResourceURI): Promise<void>;
+  /** Within one scheme. Across two it throws - that is a copy and a delete. */
+  rename(from: ResourceURI, to: ResourceURI): Promise<void>;
+  /** A provider that cannot watch gives back a disposable that does nothing. */
+  watch(uri: ResourceURI, fn: (event: 'change' | 'create' | 'delete') => void): Disposable;
+
+  viewersFor(kind: string): ResourceViewerDefinition[];
+  editorsFor(kind: string): ResourceEditorDefinition[];
+  /** Every renderer for this kind - editors, viewers and openers - best first. */
+  renderersFor(kind: string): ResourceRendererDefinition[];
+  /**
+   * The icon and tone for a resource: the renderer that opens it, then the
+   * kind and whatever it extends. Empty when nobody has said.
+   */
+  appearanceOf(resource: { kind: string }): { icon?: string; tone?: SemanticVariant };
+  actionsFor(kind: string, slot?: string): ResourceActionDefinition[];
+
+  /** The node that displays this resource, viewer chosen by the registry. */
+  nodeFor(resource: Resource, options?: { viewerId?: string; mode?: 'view' | 'edit' }): ComponentNode | null;
+}
+
+/**
+ * One way of showing a resource.
+ *
+ * A viewer, an editor and a component that declared `opens` are three ways of
+ * registering the same thing: a component that can put this kind on screen.
+ * A panel wants the list, not the three lists - which one saves is a property
+ * of the renderer, not a different registry.
+ */
+export interface ResourceRendererDefinition {
+  id: string;
+  title: string;
+  kinds: string[];
+  component: string;
+  icon?: string;
+  /** As on a kind. A renderer that declares one speaks for what it opens. */
+  tone?: SemanticVariant;
+  priority?: number;
+  when?: WhenClause;
+  /** True when this renderer can write the resource back. */
+  saves?: boolean;
+}

package/src/types/services.ts

@@ -0,0 +1,28 @@
+import type { Disposable } from './disposable.js';
+
+/**
+ * A service key is a typed token. This is a lookup table with types, not a
+ * dependency-injection container - there is no lifecycle, no scoping and no
+ * auto-wiring, on purpose.
+ */
+export interface ServiceKey<T> {
+  readonly id: string;
+  /** Never present at runtime; carries the type. */
+  readonly __type?: T;
+}
+
+export function serviceKey<T>(id: string): ServiceKey<T> {
+  return { id };
+}
+
+export interface ServiceContainer {
+  provide<T>(key: ServiceKey<T>, value: T): Disposable;
+  /** Created on first use. */
+  provideLazy<T>(key: ServiceKey<T>, factory: () => T): Disposable;
+  get<T>(key: ServiceKey<T>): T | undefined;
+  /** Throws with the key id when missing - a clear programmer error. */
+  require<T>(key: ServiceKey<T>): T;
+  has<T>(key: ServiceKey<T>): boolean;
+  /** A child container that falls back to this one. */
+  child(): ServiceContainer;
+}

package/src/types/shell.ts

@@ -0,0 +1,30 @@
+import type { Disposable } from './disposable.js';
+import type { SurfaceName } from './surface.js';
+
+/**
+ * The shell is the frame around the surfaces. Where it puts them is the whole
+ * of what a shell decides - which is why the same application renders as a
+ * dense bordered console, an airy borderless report or a full workbench by
+ * changing one registration.
+ */
+export interface ShellDefinition {
+  id: string;
+  title: string;
+  description?: string;
+  /** Component name; receives `{ surfaces, renderSurface }`. */
+  component: string;
+  /** Surfaces this shell renders. Others stay unmounted. */
+  surfaces?: SurfaceName[];
+  /** Default theme id this shell was designed against. */
+  theme?: string;
+  /** Below this width or height the shell is not offered. */
+  minSize?: { width?: number; height?: number };
+}
+
+export interface ShellRegistry {
+  register(def: ShellDefinition): Disposable;
+  get(id: string): ShellDefinition | undefined;
+  list(): ShellDefinition[];
+  /** Shells that fit the current terminal, best first. */
+  suitable(width: number, height: number): ShellDefinition[];
+}

package/src/types/store.ts

@@ -0,0 +1,148 @@
+import type { Disposable } from './disposable.js';
+import type { BindingPath, EventPath } from './graph.js';
+
+/**
+ * Scopes are lifetimes, not folders. The first segment of an absolute path
+ * names one, and `clearScope` is what makes sign-out or screen-teardown a
+ * single call rather than a cascade of resets.
+ */
+export type ScopeName =
+  | 'local'      // dies with the mount
+  | 'screen'     // dies with the screen
+  | 'session'    // dies with the process
+  | 'app'        // outlives screens; the application's own state
+  | 'global'     // outlives everything the app can clear
+  | 'summary'    // derived counts and rollups
+  | 'active'     // what is selected, application-wide
+  | 'ui'         // chrome state: collapsed, expanded, scrolled
+  | 'layout'     // surfaces, mounts, the active shell
+  | 'modus'      // the environment: size, capabilities, locale
+  | `plugins.${string}`
+  | (string & {});
+
+export type SubscribeOptions = {
+  /** Fire for changes at or below the path, not only exact hits. */
+  subtree?: boolean;
+  /** Deliver the current value immediately on subscribe. */
+  immediate?: boolean;
+};
+
+export interface ChangeRecord {
+  path: BindingPath;
+  value: unknown;
+  previous: unknown;
+}
+
+export type ComputedDefinition<T = unknown> =
+  | { from: BindingPath[]; select: (values: Record<string, unknown>) => T }
+  /** A tiny expression over the `from` paths, for computed defined as data. */
+  | { from: BindingPath[]; select: string };
+
+/**
+ * A namespace and the code that fills it. Lazy by default: nothing loads until
+ * something reads or subscribes below `namespace`.
+ */
+export interface DataProviderDefinition {
+  namespace: string;
+  load?: 'lazy' | 'eager';
+  /** Unload this many ms after the last subscriber leaves. */
+  unloadAfter?: number;
+  provider: {
+    load(store: ReactiveStore): Promise<void> | void;
+    unload?(store: ReactiveStore): Promise<void> | void;
+    loadOne?(id: string): Promise<unknown>;
+  };
+}
+
+/** Optional shape checking. Dynamic paths stay legal either way. */
+export interface PathSchema {
+  path: BindingPath;
+  /** Return null when valid, a message when not. */
+  validate(value: unknown): string | null;
+  /** Seeded when the path is first read and still empty. */
+  initial?: unknown;
+}
+
+/** Persist selected paths or subtrees across runs. */
+export interface PersistenceAdapter {
+  id: string;
+  /** Paths and subtrees this adapter owns. Subtree if it ends in `/`. */
+  paths: string[];
+  read(): Promise<Record<string, unknown>> | Record<string, unknown>;
+  write(entries: Record<string, unknown>): Promise<void> | void;
+  /** Coalesce writes by this many ms. */
+  debounceMs?: number;
+}
+
+/** Collection helpers operate on a path holding an array. */
+export interface CollectionOps<T = unknown> {
+  all(): T[];
+  at(index: number): T | undefined;
+  find(pred: (item: T, i: number) => boolean): T | undefined;
+  append(...items: T[]): void;
+  prepend(...items: T[]): void;
+  insertAt(index: number, ...items: T[]): void;
+  removeAt(index: number): void;
+  remove(pred: (item: T, i: number) => boolean): number;
+  update(pred: (item: T, i: number) => boolean, patch: Partial<T> | ((item: T) => T)): number;
+  replace(items: T[]): void;
+  filter(pred: (item: T, i: number) => boolean): T[];
+  clear(): void;
+  /** Keep at most `n` items, dropping from the front. For log tails. */
+  cap(n: number): void;
+  readonly length: number;
+}
+
+export interface ReactiveStore extends Disposable {
+  get<T = unknown>(path: BindingPath): T | undefined;
+  /** `get` with a fallback, so callers stop writing `?? default` everywhere. */
+  read<T>(path: BindingPath, fallback: T): T;
+  set(path: BindingPath, value: unknown): void;
+  /** Functional update - receives the current value. */
+  update<T = unknown>(path: BindingPath, fn: (current: T | undefined) => T): void;
+  /** Shallow-merge into an object at `path`. */
+  patch(path: BindingPath, partial: Record<string, unknown>): void;
+  /** Many writes, one notification pass. */
+  patchMany(entries: Record<BindingPath, unknown>): void;
+  delete(path: BindingPath): void;
+  has(path: BindingPath): boolean;
+
+  /** Coalesce every write inside `fn` into a single notification pass. */
+  batch<T>(fn: () => T): T;
+
+  subscribe(
+    path: BindingPath,
+    fn: (value: unknown, change: ChangeRecord) => void,
+    options?: SubscribeOptions,
+  ): Disposable;
+
+  clearScope(scope: ScopeName | string): void;
+  subscriberCount(scope: ScopeName | string): number;
+
+  computed<T = unknown>(path: BindingPath, def: ComputedDefinition<T>): Disposable;
+  collection<T = unknown>(path: BindingPath): CollectionOps<T>;
+
+  registerDataProvider(def: DataProviderDefinition): Disposable;
+  listDataProviders(): DataProviderDefinition[];
+
+  registerSchema(schema: PathSchema): Disposable;
+  registerPersistence(adapter: PersistenceAdapter): Disposable;
+  /** Load every registered persistence adapter. Call once at boot. */
+  hydrate(): Promise<void>;
+
+  /** Everything below `scope`, as a plain object. For snapshots and tests. */
+  snapshot(scope?: ScopeName | string): Record<string, unknown>;
+  restore(snapshot: Record<string, unknown>): void;
+}
+
+/**
+ * Transient events. Same path convention as the store, deliberately not the
+ * same mechanism - an event has no value to read back, which is the whole
+ * difference between `$/dialog/open` and `@/dialog/confirm`.
+ */
+export interface EventBus extends Disposable {
+  emit(path: EventPath, payload?: unknown): void;
+  on(path: EventPath, fn: (payload: unknown, path: EventPath) => void, options?: { subtree?: boolean; once?: boolean }): Disposable;
+  /** Resolve on the next emit at this path. */
+  next(path: EventPath, timeoutMs?: number): Promise<unknown>;
+}

package/src/types/stream.ts

@@ -0,0 +1,24 @@
+import type { Disposable } from './disposable.js';
+
+/**
+ * The smallest useful stream. A LogViewer should not care whether its lines
+ * come from a Node stream, an async iterable, a child process or a store path,
+ * so every source is adapted to this.
+ */
+export interface Stream<T> {
+  subscribe(observer: StreamObserver<T>): Disposable;
+  /** Best-effort stop at the source. */
+  cancel?(): void;
+}
+
+export interface StreamObserver<T> {
+  next(value: T): void;
+  error?(err: unknown): void;
+  complete?(): void;
+}
+
+export type StreamSource<T> =
+  | Stream<T>
+  | AsyncIterable<T>
+  | Iterable<T>
+  | (() => AsyncIterable<T>);