@takesix/react 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vvapnik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @takesix/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React viewer and editor for [takesix](https://github.com/vvapnik/takesix-core)
+diagrams. One screen shows at most **6 blocks**; click a block to zoom into
+its children. Links between blocks are drawn on every level, including links
+between blocks nested deep inside different parents.
+
+Use it to show an AI agent's answer as a diagram rather than a wall of text:
+render the takesix JSON the agent wrote, let the reader zoom in, refine it in
+the editor.
+
+The document format and all editing logic live in
+[`@takesix/core`](https://github.com/vvapnik/takesix-core); this package only
+renders and edits.
+
+## Install
+
+```bash
+npm install @takesix/react @takesix/core
+```
+
+Peer dependencies: `react` and `react-dom` 18 or newer.
+
+## Usage
+
+```tsx
+import { useState } from 'react'
+import { parseDocument, type TakeSixDocument } from '@takesix/core'
+import { TakeSix } from '@takesix/react'
+import '@takesix/react/style.css'
+
+export function Diagram({ json }: { json: string }) {
+  const result = parseDocument(json)
+  if (!result.ok) return <p>Invalid diagram</p>
+  return <Editor initial={result.document} />
+}
+
+function Editor({ initial }: { initial: TakeSixDocument }) {
+  const [doc, setDoc] = useState(initial)
+  const [editing, setEditing] = useState(false)
+  return (
+    <>
+      <button onClick={() => setEditing(e => !e)}>{editing ? 'Done' : 'Edit'}</button>
+      <div style={{ height: 600 }}>
+        <TakeSix document={doc} onChange={setDoc} editing={editing} />
+      </div>
+    </>
+  )
+}
+```
+
+`TakeSix` fills its container, so give the container a height. It is only the
+view: the Edit toggle belongs to your app (a toolbar, a menu).
+
+### Props
+
+| Prop | Type | Meaning |
+|---|---|---|
+| `document` | `TakeSixDocument` | The diagram. Validate untrusted input with `parseDocument` first. |
+| `onChange` | `(doc) => void` | Receives the edited document. Without it the diagram is read-only. |
+| `editing` | `boolean` | Show the edit controls. Ignored without `onChange`. |
+| `theme` | `'auto' \| 'light' \| 'dark'` | Colour theme. `auto` (default) follows the system setting. |
+| `className` | `string` | Extra class for the root element. |
+
+### Theming
+
+All colours are CSS variables on the root element (`--ts-bg`, `--ts-surface`,
+`--ts-text`, `--ts-accent`, …; see `src/TakeSix.module.css`). Pick a built-in
+theme with the `theme` prop, or override variables through `className`:
+
+```css
+.myDiagram {
+  --ts-accent: #0f9d58;
+  --ts-bg: transparent;
+}
+```
+
+### What is shown
+
+- **One level per screen**, with a breadcrumb. There is no header for the
+  opened block: if a level needs a title or summary, make it the first block.
+- **Cards** show icon, title and description, and "N more inside" when the
+  block has children (direct children only). Click anywhere on such a card to
+  open it; text stays selectable.
+
+- **Arrows**: a link between nested blocks is drawn between their ancestors on
+  the current screen. Several links between the same pair of blocks merge into
+  one arrow labelled with their labels, or with the count when there are more
+  than two. An arrow that stands for nested links is dashed.
+- **Directions**: `forward` has one arrowhead, `both` two, `none` none.
+- **Details**: a block with `details` gets a details button (on its card, and
+  in the header once opened) that opens a side panel. `details` is Markdown,
+  a safe subset rendered without HTML: `#`–`###` headings, paragraphs, `-`/`1.`
+  lists, fenced code, `**bold**`, `*italic*`, `` `code` ``, and links with
+  `http(s)`/`mailto` URLs (other schemes are shown as plain text).
+- **Sizes**: a level is one flow of blocks on a 6-column grid. Each block
+  takes a third (`S`), a half (`M`, default), two thirds (`L`) or the full
+  width (`F`); blocks wrap to the next row when they do not fit. Six `F`
+  blocks make a list, three `S` a row of tiles. A full-width card is laid out
+  as a row.
+
+### Editing
+
+In edit mode you can:
+
+- rename blocks and edit descriptions in place;
+- add and delete blocks; a level stops offering "add" at 6 blocks;
+- group blocks: "Group blocks" in the toolbar, select two or more, Group. They
+  move into a new block ("New group") where the first of them was, which frees
+  room on a full level;
+- reorder blocks by dragging the dotted handle on their left;
+- link blocks: press the arrow button on the source, then click the target.
+  The target may be on any level: while linking, open blocks ("N more inside")
+  or go back up to find it. A block's own ancestors and descendants cannot be
+  targets. Clicking a linked target removes the link; Esc or Cancel stops;
+- edit links: click an arrow or its label to change the label and direction
+  (one way, both ways, none), reverse or delete it. A merged arrow lists every
+  link it stands for, with their real endpoints;
+- write details: the details button opens the panel with a Markdown editor
+  and a live preview;
+- resize blocks: the size button (⅓ ½ ⅔ 1) cycles the size, or drag the
+  card's right edge, which snaps to the four sizes.
+
+## Development
+
+Node 24 LTS (see `.nvmrc`; with nvm: `nvm use`). `@takesix/core` comes from
+npm; to try unreleased core changes, run `npm link` in a `takesix-core` checkout
+and `npm link @takesix/core` here.
+
+```bash
+npm install
+npm run dev      # demo app from examples/
+npm test
+npm run build
+```
+
+## AI-assisted development
+
+This project is developed with the help of [Claude Code](https://claude.com/claude-code)
+(Anthropic). Commits are authored and reviewed by the maintainer.
+
+## License
+
+MIT

package/dist/BlockCard.d.ts

@@ -0,0 +1,41 @@
+import { type Block, type Size } from '@takesix/core';
+export interface CardRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Where a dragged block would land relative to this card. */
+export type DropPosition = 'before' | 'after';
+/** Grid columns (of 6) each size spans. */
+export declare const SIZE_SPAN: Record<Size, number>;
+interface Props {
+    block: Block;
+    editing: boolean;
+    onRename: (id: string, title: string) => void;
+    onDescribe: (id: string, description: string) => void;
+    onDelete: (id: string) => void;
+    onAddChild: (block: Block, cardRect: CardRect) => void;
+    onDrillIn: (block: Block, cardRect: CardRect) => void;
+    connectingFrom: string | null;
+    /** While linking: this block may be the target (not the source, its ancestor or descendant). */
+    canLinkTo: boolean;
+    isConnected: boolean;
+    onStartConnect: (id: string) => void;
+    onConnectTarget: (id: string) => void;
+    onRegisterEl: (id: string, el: HTMLDivElement | null) => void;
+    /** Drag and drop to reorder, edit mode only. */
+    isDragged: boolean;
+    dropPosition: DropPosition | null;
+    onDragStartBlock: (id: string) => void;
+    onDragOverBlock: (id: string, position: DropPosition) => void;
+    onDragEndBlock: () => void;
+    onShowDetails: (id: string) => void;
+    /** Choosing blocks to group: a click selects instead of opening. */
+    selectable: boolean;
+    selected: boolean;
+    onToggleSelect: (id: string) => void;
+    onResize: (id: string, size: Size) => void;
+}
+export declare function BlockCard({ block, editing, onRename, onDescribe, onDelete, onAddChild, onDrillIn, connectingFrom, canLinkTo, isConnected, onStartConnect, onConnectTarget, onRegisterEl, isDragged, dropPosition, onDragStartBlock, onDragOverBlock, onDragEndBlock, onShowDetails, selectable, selected, onToggleSelect, onResize, }: Props): import("react").JSX.Element;
+export {};

package/dist/DetailsPanel.d.ts

@@ -0,0 +1,11 @@
+import type { Block } from '@takesix/core';
+interface Props {
+    block: Block;
+    editing: boolean;
+    /** Saves the Markdown source; an empty string removes `details`. */
+    onChange: (details: string) => void;
+    onClose: () => void;
+}
+/** Side panel with a block's long description (`details`, Markdown). */
+export declare function DetailsPanel({ block, editing, onChange, onClose }: Props): import("react").JSX.Element;
+export {};

package/dist/LinkPopover.d.ts

@@ -0,0 +1,17 @@
+import type { Link } from '@takesix/core';
+/** Changes to one link. A key set to `undefined` removes that field. */
+export type LinkEdit = Partial<Pick<Link, 'from' | 'to' | 'label' | 'direction'>>;
+interface Props {
+    /** The document links one arrow stands for: usually one, several when merged. */
+    links: Link[];
+    /** Where the arrow's middle is, relative to the arrow layer. */
+    x: number;
+    y: number;
+    titleOf: (id: string) => string;
+    onUpdate: (link: Link, changes: LinkEdit) => void;
+    onRemove: (link: Link) => void;
+    onClose: () => void;
+}
+/** Edits the links behind one arrow: label, direction, reverse, delete. */
+export declare function LinkPopover({ links, x, y, titleOf, onUpdate, onRemove, onClose }: Props): import("react").JSX.Element;
+export {};

package/dist/TakeSix.d.ts

@@ -0,0 +1,18 @@
+import { type TakeSixDocument } from '@takesix/core';
+export interface TakeSixProps {
+    /** The diagram to show. Expected to be valid: run `parseDocument` from `@takesix/core` on untrusted input. */
+    document: TakeSixDocument;
+    /** Called with the edited document. Without it the diagram stays read-only. */
+    onChange?: (document: TakeSixDocument) => void;
+    /**
+     * Show the edit controls. The toggle lives in the host app (e.g. its toolbar),
+     * so the component itself is only the view. Ignored without `onChange`.
+     */
+    editing?: boolean;
+    /** Colour theme. `auto` (default) follows the system setting. */
+    theme?: Theme;
+    className?: string;
+}
+export type Theme = 'light' | 'dark' | 'auto';
+/** Viewer and editor for a takesix document: one level on screen, click a block to open it. */
+export declare function TakeSix({ document: doc, onChange, editing: editingProp, theme, className }: TakeSixProps): import("react").JSX.Element;

package/dist/Viewer.d.ts

@@ -0,0 +1,30 @@
+import { type Size, type Link, type TakeSixDocument } from '@takesix/core';
+import { type LinkEdit } from './LinkPopover.js';
+/** Edits the viewer asks for. All of them are optional: without one, the matching control is hidden. */
+export interface ViewerActions {
+    rename: (id: string, title: string) => void;
+    describe: (id: string, description: string) => void;
+    remove: (id: string) => void;
+    /** Adds an empty block under `parentId` (`null` = top level). */
+    add: (parentId: string | null) => void;
+    /** Sets a block's width on its level. */
+    setSize: (id: string, size: Size) => void;
+    /** Links `fromId` → `toId`, or removes that link when it exists. */
+    toggleLink: (fromId: string, toId: string) => void;
+    /** Moves a block to position `index` among the children of `parentId`. */
+    move: (id: string, parentId: string | null, index: number) => void;
+    /** Edits one link, found by identity (links in files may have no id). */
+    updateLink: (link: Link, changes: LinkEdit) => void;
+    removeLink: (link: Link) => void;
+    /** Saves a block's Markdown details; an empty string removes them. */
+    setDetails: (id: string, details: string) => void;
+    /** Wraps sibling blocks into a new parent block, freeing room on the level. */
+    group: (ids: string[]) => void;
+}
+interface Props {
+    document: TakeSixDocument;
+    editing: boolean;
+    actions: ViewerActions;
+}
+export declare function Viewer({ document: doc, editing, actions }: Props): import("react").JSX.Element;
+export {};

package/dist/geometry.d.ts

@@ -0,0 +1,50 @@
+export interface Rect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export type Edge = 'left' | 'right' | 'top' | 'bottom';
+export interface ArrowRequest {
+    key: string;
+    fromId: string;
+    toId: string;
+    /** An arrowhead is drawn at this end: the path stops at the head's base, short of the card. */
+    headAtStart?: boolean;
+    headAtEnd?: boolean;
+}
+/** Space between an arrowhead's tip and the card it points at. */
+export declare const HEAD_GAP = 4;
+/** Length of the arrowhead. The path ends at its base and the head is drawn
+    beyond it, so the line never shows through the tip. */
+export declare const HEAD_LENGTH = 10;
+export interface ArrowPath {
+    key: string;
+    /** SVG path data, relative to the container. */
+    d: string;
+    /** Middle of the curve, for the label. */
+    mid: Point;
+    /** Runs from one card's top/bottom edge to the other's: put the label beside it, not on it. */
+    vertical: boolean;
+}
+export declare function determineEdges(fromRect: Rect, toRect: Rect, obstacleRects: Rect[]): {
+    exitEdge: Edge;
+    entryEdge: Edge;
+};
+export declare function edgePoint(rect: Rect, edge: Edge, idx: number, total: number, origin: Point): Point;
+/** Cubic Bézier control points from `p1` (on `exitEdge`) to `p2` (on `entryEdge`). */
+export declare function controlPoints(fromRect: Rect, toRect: Rect, origin: Point, exitEdge: Edge, entryEdge: Edge, p1: Point, p2: Point): [Point, Point];
+/** Point of a cubic Bézier at t = 0.5. */
+export declare function bezierMid(p0: Point, c1: Point, c2: Point, p3: Point): Point;
+/**
+ * Routes all arrows of one screen. Exits and entries on the same edge of the
+ * same card share one pool of slots, so arrows never start or end on top of
+ * each other. Arrows whose cards have no rect are skipped.
+ */
+export declare function routeArrows(requests: ArrowRequest[], rects: Map<string, Rect>, container: Rect): ArrowPath[];

package/dist/icons.d.ts

@@ -0,0 +1,6 @@
+export declare function PlusIcon({ size }: {
+    size?: number;
+}): import("react").JSX.Element;
+export declare function CrossIcon(): import("react").JSX.Element;
+export declare function ArrowRightIcon(): import("react").JSX.Element;
+export declare function DetailsIcon(): import("react").JSX.Element;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { TakeSix, type TakeSixProps, type Theme } from './TakeSix.js';
+export type { TakeSixDocument, Block, Link, Size } from '@takesix/core';