@react-x11/components 0.1.0 → 0.2.1

package/src/internal/widget.ts

@@ -0,0 +1,92 @@
+// The bits of react-x11 that a value widget needs and react-x11 does not
+// export — the change event every one of them emits, and the dismiss-on-blur
+// subscription every popup one needs.
+//
+// It lived in `src/calendar/` while the calendar was the only widget out
+// here; `<ColorPicker>` is the second, which is exactly the promotion
+// `AGENTS.md` describes for `src/internal/`.
+//
+// Everything else these widgets stand on is public — `useTheme`,
+// `createStyles`, `useAnchor`/`useAnchorTracking`, the `XK_*` keysyms, the
+// host elements, and `tint` off `react-x11/style`, which used to be vendored
+// here and is not any more. These two are what is left, and they are
+// collected here rather than scattered so the list stays short and visible.
+// Each is small and pure; if core ever puts one on its exports map, delete it
+// from here and import it, the way `tint` was deleted.
+
+import { useEffect, useRef } from 'react';
+import type { RefObject } from 'react';
+
+/** The `target` a {@link WidgetChangeEvent} carries. */
+export interface ChangeTarget<T> {
+  type: string;
+  name: string | undefined;
+  value: T;
+}
+
+/**
+ * The change event the value widgets hand their `onChange`.
+ *
+ * One signature across react-x11's widgets, and this keeps to it so that
+ * `onChange={formik.handleChange}` works here too: a form library reads the
+ * field out of `ev.target`, and `{ type, name, value }` is exactly the shape
+ * formik's `handleChange` and react-hook-form's event reader destructure.
+ * `type` is what tells them a date from a text field, which is why it is set
+ * even though nothing in react-x11 reads it.
+ *
+ * `target` is a plain descriptor rather than a node: a widget is a composition
+ * of nodes with no single element holding its value, so there is nothing
+ * honest to point at. There is no `preventDefault` either — the value has
+ * already changed by the time the handler runs.
+ */
+export interface WidgetChangeEvent<T> {
+  type: 'change';
+  target: ChangeTarget<T>;
+  currentTarget: ChangeTarget<T>;
+  name: string | undefined;
+  value: T;
+}
+
+export function changeEvent<T>(
+  type: string,
+  name: string | undefined,
+  value: T,
+): WidgetChangeEvent<T> {
+  const target: ChangeTarget<T> = { type, name, value };
+  return { type: 'change', target, currentTarget: target, name, value };
+}
+
+/** The slice of the owning window a dismiss-on-blur subscription needs.
+ *  `DrawnNode` in react-x11's public types does not carry `root`, because a
+ *  ref's contract is geometry and focus rather than the window's own events. */
+interface NodeWithRoot {
+  root?: {
+    onWindowFocusChange?: (fn: (focused: boolean) => void) => () => void;
+  } | null;
+}
+
+/**
+ * Close a popup when the *window* loses focus.
+ *
+ * A trigger keeps its own focus while its override-redirect popup is up, so
+ * the trigger's `onBlur` never hears that the application went to the
+ * background — and a menu or a calendar left floating over another app's
+ * window is the bug that follows.
+ */
+export function useDismissOnWindowBlur(
+  ref: RefObject<unknown>,
+  active: boolean,
+  onDismiss: () => void,
+): void {
+  const onDismissRef = useRef(onDismiss);
+  onDismissRef.current = onDismiss;
+
+  useEffect(() => {
+    if (!active) return undefined;
+    const root = (ref.current as NodeWithRoot | null)?.root;
+    if (!root?.onWindowFocusChange) return undefined;
+    return root.onWindowFocusChange((focused: boolean) => {
+      if (!focused) onDismissRef.current?.();
+    });
+  }, [active, ref]);
+}

package/src/markdown/ast.ts

@@ -0,0 +1,163 @@
+// The markdown AST `parse.ts` produces and `index.ts` renders. Deliberately
+// small: it is the GFM constructs this component draws, not a general
+// mdast — but it is shaped so that growing it stays additive. In particular
+// `component` is reserved for the MDX direction: a parser extension can emit
+// one without the renderer, the selection model or the caches changing shape
+// (see "MDX" in index.ts).
+
+/** Inline content, inside a paragraph, heading, list item or table cell. */
+export type InlineNode =
+  | TextInline
+  | CodeInline
+  | EmphasisInline
+  | LinkInline
+  | BreakInline
+  | ComponentInline;
+
+/** A run of plain text. Softbreaks arrive collapsed to spaces. */
+export interface TextInline {
+  type: 'text';
+  text: string;
+}
+
+/** An inline code span. */
+export interface CodeInline {
+  type: 'code';
+  text: string;
+}
+
+/** `strong` is `**`, `em` is `*`, `del` is `~~`. */
+export interface EmphasisInline {
+  type: 'strong' | 'em' | 'del';
+  children: InlineNode[];
+}
+
+/**
+ * A link, or an image rendered as its alt text (this component draws no
+ * remote bitmaps — see index.ts). `href: null` is a link still streaming
+ * in: the text is styled as a link but there is nothing to navigate to yet.
+ */
+export interface LinkInline {
+  type: 'link';
+  href: string | null;
+  /** True when this was `![alt](src)` — the href is the image source. */
+  image: boolean;
+  children: InlineNode[];
+}
+
+/** A hard line break (two trailing spaces, or a trailing backslash). */
+export interface BreakInline {
+  type: 'break';
+}
+
+/**
+ * Reserved for MDX: `<Chart data={…} />` would parse to one of these. The
+ * current parser never emits it; the renderer maps unknown names to plain
+ * text so a future parser upgrade cannot crash an older renderer.
+ */
+export interface ComponentInline {
+  type: 'component';
+  name: string;
+  attributes: Record<string, string>;
+  children: InlineNode[];
+}
+
+/** Block-level content. */
+export type BlockNode =
+  | ParagraphBlock
+  | HeadingBlock
+  | CodeBlock
+  | QuoteBlock
+  | ListBlock
+  | TableBlock
+  | RuleBlock;
+
+export interface ParagraphBlock {
+  type: 'paragraph';
+  children: InlineNode[];
+}
+
+export interface HeadingBlock {
+  type: 'heading';
+  /** 1–6. Setext `===` is 1, `---` is 2. */
+  depth: number;
+  children: InlineNode[];
+}
+
+/** A fenced or indented code block. Text has no trailing newline. */
+export interface CodeBlock {
+  type: 'code';
+  /** First word of the info string, lowercased — `''` when absent. */
+  lang: string;
+  text: string;
+  /**
+   * False when the closing fence has not arrived. During streaming that is
+   * the normal state of the last block and not worth signalling to the
+   * user; a renderer could badge it if it wanted to.
+   */
+  closed: boolean;
+}
+
+export interface QuoteBlock {
+  type: 'quote';
+  children: BlockNode[];
+}
+
+export interface ListBlock {
+  type: 'list';
+  ordered: boolean;
+  /** Start number of an ordered list; 1 for bullet lists. */
+  start: number;
+  /**
+   * A tight list renders items without paragraph spacing between them —
+   * the CommonMark distinction, decided by blank lines in the source.
+   */
+  tight: boolean;
+  items: ListItem[];
+}
+
+export interface ListItem {
+  /** `null` for a plain item; true/false for a GFM task checkbox. */
+  checked: boolean | null;
+  children: BlockNode[];
+}
+
+export type TableAlign = 'left' | 'center' | 'right' | null;
+
+export interface TableBlock {
+  type: 'table';
+  /** One entry per column, from the delimiter row. */
+  align: TableAlign[];
+  /** Header cells. Always exactly `align.length` long. */
+  header: InlineNode[][];
+  /** Body rows, each padded or truncated to `align.length` cells. */
+  rows: InlineNode[][][];
+}
+
+export interface RuleBlock {
+  type: 'rule';
+}
+
+/** What `parse` returns. */
+export interface Document {
+  blocks: BlockNode[];
+  /**
+   * The raw source of each top-level block, index-aligned with `blocks`.
+   * This is the streaming cache key: a block whose raw text did not change
+   * between two parses produced an equal AST, so a renderer can reuse
+   * everything it derived from it (see index.ts).
+   */
+  raws: string[];
+}
+
+export interface ParseOptions {
+  /**
+   * Treat the end of input as "more is coming" (default true): unclosed
+   * emphasis, code spans and links that reach the end of the source are
+   * completed instead of falling back to literal text, half-arrived
+   * constructs (`![alt](…`, a lone trailing `**`, a bare `#`) are hidden,
+   * and an ambiguous final line (`---` that could still become a setext
+   * underline or a rule) is held back. Pass false for text that is final.
+   */
+  partial?: boolean;
+}

package/src/markdown/hx.ts

@@ -0,0 +1,51 @@
+// `React.createElement`, typed against react-x11's host elements.
+//
+// The library writes `h(...)` rather than JSX — a convention inherited from
+// core, and worth keeping so moving code between the two repos stays a
+// rename. But `React.createElement`'s own overloads are `@types/react`'s, and
+// they describe the DOM: a `<box onKeyDown>` handler is checked against
+// React's `KeyboardEvent`, not react-x11's, and the whole props object is
+// measured against `DOMAttributes`. Everything interesting fails.
+//
+// So the element name is looked up in react-x11's own element table instead.
+// `hx('box', …)` gets `<box>`'s real props — `ev.keysym` on a key handler,
+// `onDraw` on a `<canvas>` — and `hx('div', …)` is an error, which is the
+// same guarantee the JSX namespace gives `examples/` and `test/types/`.
+import React from 'react';
+import type { Key, ReactElement, ReactNode } from 'react';
+import type { ReactX11Elements, Theme } from 'react-x11';
+
+/** The host elements, by name. */
+export type Host = ReactX11Elements;
+
+/**
+ * What every element takes on top of its own props.
+ *
+ * `theme` is honoured by **every** node — `Node.theme` merges `props.theme`
+ * over the inherited palette, whatever the kind — but react-x11's element
+ * declarations only put it on `<window>`. A widget re-declares the theme it
+ * read from context onto its own root so that `$token` values still resolve
+ * inside a `<popup>`, which is a separate window and does not inherit the
+ * trigger's node tree. So the prop is real; only the declaration is narrow.
+ */
+interface CommonProps {
+  key?: Key;
+  /** `Theme` is listed alongside the record because it is an interface, and
+   *  an interface has no implicit index signature — so the palette `useTheme`
+   *  hands back is not assignable to the record react-x11 declares. */
+  theme?: Theme | Record<string, string | number>;
+}
+
+export function hx<K extends keyof Host>(
+  type: K,
+  // `theme` is dropped from the element's own props before the merge:
+  // `<window>` and `<popup>` already declare it, narrower, and intersecting
+  // the two would demand a value satisfying both.
+  props?: (Omit<Host[K], 'theme'> & CommonProps) | null,
+  ...children: ReactNode[]
+): ReactElement {
+  // The cast is the whole point of the wrapper: `createElement`'s string
+  // overload insists on DOM props, and the signature above has already
+  // checked these against the element that will actually receive them.
+  return React.createElement(type as string, props as never, ...children);
+}