@neoinkjs/components 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@neoinkjs/components",
+  "version": "0.1.0",
+  "description": "Box, Text, Spacer, Newline, Static, Transform — the React components for neoink.",
+  "license": "MIT",
+  "author": "Nicholas Zolton",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NicholasZolton/neoink.git",
+    "directory": "packages/components"
+  },
+  "homepage": "https://github.com/NicholasZolton/neoink#readme",
+  "keywords": [
+    "neovim",
+    "nvim",
+    "react",
+    "tui",
+    "terminal",
+    "react-reconciler",
+    "ink"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@neoinkjs/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0"
+  }
+}

package/src/background-context.ts

@@ -0,0 +1,13 @@
+import { createContext } from "react";
+
+/**
+ * Ambient background color set by the nearest ancestor `<Box backgroundColor>`.
+ * `<Text>` reads this as a fallback when it has no `backgroundColor` of its
+ * own, so text nested inside a colored box inherits the box's background
+ * (matching Ink — see §7 of the ink-architecture-digest). `undefined` means
+ * "no ancestor Box set one" (or there is no ancestor Box at all).
+ *
+ * Internal to `@neoinkjs/components` — not re-exported from `index.ts`. `Box`
+ * is the only producer, `Text` the only consumer.
+ */
+export const backgroundContext = createContext<string | undefined>(undefined);

package/src/box.tsx

@@ -0,0 +1,142 @@
+import React, { forwardRef } from "react";
+import type { ReactNode, Ref } from "react";
+import type { AriaRole, AriaState, NeoElement, Styles, TextStyle } from "@neoinkjs/core";
+import { DEFAULT_BOX_STYLE as CORE_DEFAULT_BOX_STYLE, useIsScreenReaderEnabled } from "@neoinkjs/core";
+import { backgroundContext } from "./background-context";
+import { Text } from "./text";
+
+/**
+ * The layout-affecting subset of `Styles`: everything except the cosmetic
+ * `TextStyle` keys (inapplicable to `<Box>`) and `textWrap` (a `<Text>`-only
+ * concern). Deriving this via `Omit` keeps it in sync with `Styles`
+ * automatically — no re-listing of layout keys. Note `borderColor`/
+ * `borderBackgroundColor` and their per-edge variants are NOT part of
+ * `TextStyle`, so they already flow through this `Omit` untouched.
+ */
+type BoxNodeStyle = Omit<Styles, keyof TextStyle | "textWrap">;
+
+/**
+ * `backgroundColor` IS a `TextStyle` key, so the `Omit` above drops it —
+ * unlike border colors, it has to be re-added explicitly. It's still a
+ * cosmetic `<Box>` prop (Ink lets `<Box>` set it directly, not just via
+ * inheritance), so `<Box>` writes it into `style` and also fans it out to
+ * descendant `<Text>` via `backgroundContext`.
+ */
+type BoxNodeStyleWithBackground = BoxNodeStyle & Pick<Styles, "backgroundColor">;
+
+export type BoxProps = BoxNodeStyleWithBackground & {
+  children?: ReactNode;
+  /**
+   * A label for the element for screen readers. In screen-reader mode
+   * (`useIsScreenReaderEnabled()`), this REPLACES `children` in the box's
+   * screen-reader output — matches Ink's `<Box>` `aria-label` exactly.
+   */
+  "aria-label"?: string;
+  /**
+   * Hides the element (and its subtree) from screen readers. Has NO effect
+   * outside screen-reader mode — matches Ink: `aria-hidden` never changes a
+   * normal render's visual output.
+   */
+  "aria-hidden"?: boolean;
+  /** The element's ARIA role, surfaced in screen-reader output as a `"<role>: "` prefix. */
+  "aria-role"?: AriaRole;
+  /** The element's ARIA state, surfaced in screen-reader output as a `"(<flags>) "` prefix. */
+  "aria-state"?: AriaState;
+};
+
+/**
+ * Layout defaults merged *under* the caller's props, matching Ink's `<Box>`
+ * defaults. Re-exported (narrowed to `BoxNodeStyle`) so the fallback flex
+ * behavior can't drift from what callers expect when they omit these props —
+ * `<Transform>` and `<Static>`, which also emit a `neoink-box`, spread this
+ * as their base rather than re-listing the same triple. The actual literal
+ * values live in `@neoinkjs/core`'s `style.ts` (`DEFAULT_BOX_STYLE`), NOT
+ * here — that package's own `components/error-overview.tsx` needs the same
+ * defaults but can't import this `<Box>` COMPONENT (that would make
+ * `@neoinkjs/core` depend on `@neoinkjs/components`, which already depends on
+ * `core` — a cycle), so the raw values are defined once in `core` and both
+ * this re-export and that file build on them.
+ *
+ * Deliberately field-by-field, NOT `{ ...CORE_DEFAULT_BOX_STYLE }`: `Styles`
+ * (core's constant's type) is a strict superset of `BoxNodeStyle` (it also
+ * allows every `TextStyle`/`textWrap` key `BoxNodeStyle`'s `Omit` exists to
+ * exclude), and TypeScript's excess-property check — the thing that would
+ * catch a future `DEFAULT_BOX_STYLE` in core accidentally growing a stray
+ * cosmetic key — only fires for a FRESH object literal, not for values
+ * copied in via a spread. Spreading here would silently defeat that check
+ * (verified: temporarily adding `color: "red"` to core's constant compiled
+ * with zero errors under a spread-based version of this line); listing each
+ * field explicitly keeps it real.
+ */
+export const DEFAULT_BOX_STYLE: BoxNodeStyle = {
+  flexDirection: CORE_DEFAULT_BOX_STYLE.flexDirection,
+  flexGrow: CORE_DEFAULT_BOX_STYLE.flexGrow,
+  flexShrink: CORE_DEFAULT_BOX_STYLE.flexShrink,
+  flexWrap: CORE_DEFAULT_BOX_STYLE.flexWrap,
+};
+
+/**
+ * A layout container. Flattens its layout props (Ink-style) into a single
+ * `style` object — defaults first, then the passed props — and renders a
+ * `neoink-box` host node. When `backgroundColor` is set, wraps `children` in
+ * a `backgroundContext.Provider` so descendant `<Text>` without their own
+ * `backgroundColor` inherit it (Ink behavior — see §7 of the architecture
+ * digest).
+ *
+ * Forwards a `ref` to the underlying `neoink-box` host element — the
+ * reconciler's `getPublicInstance` resolves it to that element's `NeoElement`
+ * (see `@neoinkjs/core`'s `reconciler.ts`), so `ref.current` is exactly what
+ * `measureElement()`/`useBoxMetrics()` expect. Matches Ink's `forwardRef`
+ * `<Box>`.
+ *
+ * Screen-reader accessibility (Task 6), ported from Ink's `<Box>`
+ * (`src/components/Box.tsx`) field for field:
+ * - `aria-hidden`: when `useIsScreenReaderEnabled()` is true, returns `null`
+ *   — the whole subtree is omitted, exactly like Ink. Outside screen-reader
+ *   mode this is a no-op: a normal render never reads it.
+ * - `aria-label`: rendered (via `<Text>`, standing in for Ink's raw
+ *   `<ink-text>`) and used AS this box's content — instead of `children` —
+ *   only when `useIsScreenReaderEnabled()` is true. A non-screen-reader
+ *   render always uses `children`, regardless of `aria-label`.
+ * - `aria-role`/`aria-state`: always attached to the node as
+ *   `internal_accessibility` (Ink does the same — its `internal_accessibility`
+ *   prop is unconditional, not gated on screen-reader mode); the ordinary
+ *   paint path ignores it, only `renderNodeToScreenReaderOutput` reads it.
+ */
+export const Box = forwardRef(function Box(
+  props: BoxProps,
+  ref: Ref<NeoElement>,
+): React.ReactElement | null {
+  const {
+    children,
+    "aria-label": ariaLabel,
+    "aria-hidden": ariaHidden,
+    "aria-role": role,
+    "aria-state": ariaState,
+    ...layoutProps
+  } = props;
+  const style: BoxNodeStyleWithBackground = { ...DEFAULT_BOX_STYLE, ...layoutProps };
+  const isScreenReaderEnabled = useIsScreenReaderEnabled();
+
+  if (isScreenReaderEnabled && ariaHidden) {
+    return null;
+  }
+
+  const label = ariaLabel ? React.createElement(Text, null, ariaLabel) : undefined;
+  const boxChildren = isScreenReaderEnabled && label ? label : children;
+
+  const content =
+    style.backgroundColor !== undefined
+      ? React.createElement(
+          backgroundContext.Provider,
+          { value: style.backgroundColor },
+          boxChildren,
+        )
+      : boxChildren;
+
+  return React.createElement(
+    "neoink-box",
+    { style, ref, internal_accessibility: { role, state: ariaState } },
+    content,
+  );
+});

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Box } from "./box";
+export type { BoxProps } from "./box";
+export { Text } from "./text";
+export type { TextProps } from "./text";
+export { Spacer } from "./spacer";
+export { Newline } from "./newline";
+export type { NewlineProps } from "./newline";
+export { Transform } from "./transform";
+export type { TransformProps } from "./transform";
+export { Static } from "./static";
+export type { StaticProps } from "./static";

package/src/newline.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { Text } from "./text";
+
+export interface NewlineProps {
+  count?: number;
+}
+
+/**
+ * Renders `count` newline characters as text content. Only meaningful inside
+ * a `<Text>`: it delegates to `<Text>`, which the reconciler remaps to a
+ * cosmetic `neoink-virtual-text` node when nested inside another `<Text>`
+ * (see `createInstance` in `@neoinkjs/core`'s reconciler), so its newline
+ * string composes into the ancestor `<Text>`'s squashed content exactly like
+ * `<Text>Hello <Text>World</Text></Text>` does.
+ */
+export function Newline({ count = 1 }: NewlineProps): React.ReactElement {
+  if (count < 0) {
+    throw new Error(`<Newline count> must be >= 0, got ${count}`);
+  }
+
+  return React.createElement(Text, null, "\n".repeat(count));
+}

package/src/spacer.tsx

@@ -0,0 +1,13 @@
+import React from "react";
+import { Box } from "./box";
+
+/**
+ * A flexible filler: a `<Box>` that grows to consume any remaining space
+ * along its parent's main axis, pushing its siblings toward opposite ends
+ * of the parent. Inherits `Box`'s default `flexShrink: 1`, so — matching
+ * Ink's `<Spacer>` — it can still shrink below its grown size in an
+ * overflowing row.
+ */
+export function Spacer(): React.ReactElement {
+  return React.createElement(Box, { flexGrow: 1 });
+}

package/src/static.tsx

@@ -0,0 +1,53 @@
+import React from "react";
+import type { ReactNode } from "react";
+import type { Styles } from "@neoinkjs/core";
+import { DEFAULT_BOX_STYLE } from "./box";
+
+export interface StaticProps<T> {
+  items: readonly T[];
+  children: (item: T, index: number) => ReactNode;
+}
+
+/**
+ * Column layout for a stacked list of static entries. Spreads `<Box>`'s
+ * shared `DEFAULT_BOX_STYLE` (single source of truth for the flex-default
+ * triple) and overrides only `flexDirection` to `"column"`.
+ */
+const STATIC_NODE_STYLE: Styles = {
+  ...DEFAULT_BOX_STYLE,
+  flexDirection: "column",
+};
+
+/**
+ * Renders `items` once each, via `children(item, index)`, stacked in a
+ * column.
+ *
+ * Ink's `<Static>` renders its subtree exactly once and then removes it from
+ * the live tree, so the *persistent* render loop's per-frame diff never
+ * repaints it — the content is written once, above the diffed region, and
+ * never re-erased (see `internal_static`/`isStaticDirty` in Ink's DOM).
+ * neoink's `<Static>` instead keeps rendering the FULL `items` array every
+ * commit (simpler: no internal index/slicing state) and tags the wrapping
+ * node `internal_static` (a typed field on `NeoElement`, see `@neoinkjs/core`'s
+ * `dom.ts`); it's `@neoinkjs/core`'s persistent render loop
+ * (`instance.ts`/`render.ts`) that re-derives the equivalent of Ink's
+ * once-only semantics — finding this subtree, diffing its growing output
+ * against what it already emitted, and writing only the new suffix, once,
+ * above the diffed dynamic frame. `renderToString`'s one-shot mount has no
+ * persistent frame to dedup against, so there `<Static>` simply renders
+ * inline, in order, like any other content.
+ *
+ * Like `<Transform>`, its host element is `neoink-box` — a deliberate neoink
+ * design choice, not Ink parity. As a result `<Static>` can't be nested
+ * inside a `<Text>` subtree: the reconciler throws (`<Box>` can't be nested
+ * inside `<Text>`) by design.
+ */
+export function Static<T>(props: StaticProps<T>): React.ReactElement {
+  const { items, children } = props;
+
+  return React.createElement(
+    "neoink-box",
+    { style: STATIC_NODE_STYLE, internal_static: true },
+    items.map((item, index) => children(item, index)),
+  );
+}

package/src/text.tsx

@@ -0,0 +1,82 @@
+import React, { useContext } from "react";
+import type { ReactNode } from "react";
+import { DEFAULT_TEXT_WRAP, TEXT_STYLE_KEYS, useIsScreenReaderEnabled } from "@neoinkjs/core";
+import type { Styles, TextStyle } from "@neoinkjs/core";
+import { backgroundContext } from "./background-context";
+
+export interface TextProps extends TextStyle {
+  wrap?: Styles["textWrap"];
+  children?: ReactNode;
+  /**
+   * A label for the element for screen readers. In screen-reader mode
+   * (`useIsScreenReaderEnabled()`), this REPLACES `children` — matches
+   * Ink's `<Text>` `aria-label` exactly. Note: unlike `<Box>`, Ink's
+   * `<Text>` has no `aria-role`/`aria-state` — neither does neoink's.
+   */
+  "aria-label"?: string;
+  /**
+   * Hides the element from screen readers. Has NO effect outside
+   * screen-reader mode — matches Ink.
+   */
+  "aria-hidden"?: boolean;
+}
+
+/** The subset of `Styles` a `<Text>` node ever writes: `textWrap` + the cosmetic keys. */
+type TextNodeStyle = Pick<Styles, keyof TextStyle | "textWrap">;
+
+/**
+ * Renders text. Builds a `style` object carrying `textWrap` (defaulting to
+ * `"wrap"`) plus whichever cosmetic keys the caller actually set — an unset
+ * prop is omitted rather than written as `color: undefined`, so it never
+ * shadows an inherited/default style at paint time. Reuses core's
+ * `TEXT_STYLE_KEYS` (the same list `extractTextStyle` in the reconciler
+ * consumes) so the two never drift apart. Renders `null` when the effective
+ * content — `children`, or `aria-label` in screen-reader mode (see below) —
+ * is `null`/`undefined` (no `neoink-text` node at all).
+ *
+ * `backgroundColor` falls back to the nearest ancestor `<Box backgroundColor>`
+ * (read via `backgroundContext`) when this `<Text>` doesn't set its own —
+ * matching Ink's inheritance. `useContext` is called unconditionally, before
+ * the early-return below, so it stays consistent across renders regardless
+ * of whether `children` is present.
+ *
+ * Screen-reader accessibility (Task 6), ported from Ink's `<Text>`
+ * (`src/components/Text.tsx`) field for field:
+ * - `aria-label`: when `useIsScreenReaderEnabled()` is true AND set, stands
+ *   in for `children` (`childrenOrAriaLabel` below) — so `<Text aria-label="x" />`
+ *   with no children still renders `"x"` in screen-reader mode. Outside
+ *   screen-reader mode this is a no-op: `children` is always used.
+ * - `aria-hidden`: when `useIsScreenReaderEnabled()` is true, returns `null`
+ *   — checked AFTER the null-content check below, exactly mirroring Ink's
+ *   ordering (`Text.tsx` computes `childrenOrAriaLabel`/its null-check first,
+ *   then the `aria-hidden` check, right before constructing `<ink-text>`).
+ */
+export function Text(props: TextProps): React.ReactElement | null {
+  const { wrap, children, "aria-label": ariaLabel, "aria-hidden": ariaHidden = false } = props;
+  const inheritedBackgroundColor = useContext(backgroundContext);
+  const isScreenReaderEnabled = useIsScreenReaderEnabled();
+
+  const childrenOrAriaLabel = isScreenReaderEnabled && ariaLabel ? ariaLabel : children;
+
+  if (childrenOrAriaLabel === null || childrenOrAriaLabel === undefined) {
+    return null;
+  }
+
+  if (isScreenReaderEnabled && ariaHidden) {
+    return null;
+  }
+
+  const style: TextNodeStyle = { textWrap: wrap ?? DEFAULT_TEXT_WRAP };
+  for (const key of TEXT_STYLE_KEYS) {
+    const value = props[key];
+    if (value !== undefined) {
+      (style[key] as TextStyle[typeof key]) = value;
+    }
+  }
+
+  if (style.backgroundColor === undefined && inheritedBackgroundColor !== undefined) {
+    style.backgroundColor = inheritedBackgroundColor;
+  }
+
+  return React.createElement("neoink-text", { style }, childrenOrAriaLabel);
+}

package/src/transform.tsx

@@ -0,0 +1,44 @@
+import React from "react";
+import type { ReactNode } from "react";
+import type { LineTransform } from "@neoinkjs/core";
+import { DEFAULT_BOX_STYLE } from "./box";
+
+export interface TransformProps {
+  /**
+   * A pure text→text mapping applied to each line of the squashed content
+   * beneath this node (e.g. uppercasing). Unlike Ink's ANSI-emitting
+   * `<Transform>`, neoink's transform never carries styling — that stays
+   * `<Text>`'s job — it only ever rewrites line content.
+   */
+  transform: LineTransform;
+  children?: ReactNode;
+}
+
+/**
+ * Wraps `children` in a `neoink-box` carrying `internal_transform`. At paint
+ * time (`renderNodeToOutput` in `@neoinkjs/core`), every descendant
+ * `<Text>`'s squashed + wrapped lines are passed through this (and any
+ * enclosing `<Transform>`'s) transform before being written — nested
+ * `<Transform>`s compose inner-out. Uses `<Box>`'s shared `DEFAULT_BOX_STYLE`
+ * (same source, not a re-listed copy) so the wrapper lays out like a plain
+ * `<Box>` around the same children.
+ *
+ * Architecture note — a deliberate neoink divergence from Ink, NOT parity:
+ * Ink's `<Transform>` renders an `ink-text` node (`<ink-text
+ * internal_transform=...>`), so upstream it CAN be nested inside `<Text>`.
+ * neoink instead hosts a `neoink-box`, a P2 design choice. The consequence is
+ * a real, intentional limitation: because the reconciler throws when a
+ * `neoink-box` is instantiated inside a `<Text>` subtree (`<Box>` can't be
+ * nested inside `<Text>`), `<Transform>` can only wrap a `<Text>`/`<Box>`
+ * from the outside — nesting it as an inline child of `<Text>` throws loudly
+ * by design.
+ */
+export function Transform(props: TransformProps): React.ReactElement {
+  const { transform, children } = props;
+
+  return React.createElement(
+    "neoink-box",
+    { style: DEFAULT_BOX_STYLE, internal_transform: transform },
+    children,
+  );
+}