carterkit 0.3.1__tar.gz → 0.5.0__tar.gz

{carterkit-0.3.1 → carterkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.3.1
+Version: 0.5.0
 Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
 Author: Carter Beaudoin
 License-Expression: MIT
@@ -51,25 +51,70 @@ carterkit.examples("button")    # documented example snippets
 
 ## Build a layout
 
-The fluent `Layout` builder composes **typed builders** (`build.<control>`) and
-**binding helpers** (`bind`) — all generated from / shaped by the bundled docs, so
-unknown control types and bad enum values raise instead of silently shipping a broken
-layout:
+Controls are **methods on the layout**, ids are positional, tabs and groups are context
+managers, and bindings fold into kwargs. Each control method returns a **handle** you can
+use as a binding target or patch later. Unknown control types and bad enum values raise
+instead of silently shipping a broken layout:
 
 ```python
-from carterkit import Layout, build, bind
-
-lay = (Layout("Dashboard", columns=4, rows=4)
-       .connect("ws://192.168.1.50:8765", channel="home")
-       .tab("Main", icon="gauge")
-       .add(build.gauge(id="cpu", label="CPU", min=0, max=100,
-                        sync=[bind.listen("cpu", filter={"msg_type": "metrics"})]),
-            default_span=[2, 2])
-       .add(build.button(id="refresh", label="Refresh", action=bind.action("refresh"))))
-
-print(lay.findings())    # schema + grid + binding lint against the bundled catalog
-help(build.gauge)        # ← prints the gauge documentation, straight from the docs
-layout = lay.layout      # the composed dict, ready to push/save
+from carterkit import Layout
+
+with Layout("Dashboard", cols=4, rows=4) as ui:
+    ui.connect("ws://192.168.1.50:8765", channel="home")
+    with ui.tab("Main", icon="gauge"):
+        cpu = ui.gauge("cpu", label="CPU", min=0, max=100, span=(2, 2),
+                       listen="cpu", when={"msg_type": "metrics"})
+        ui.status_light("warn", visible=cpu > 90)      # handle → visibility condition
+        ui.button("refresh", label="Refresh", send="refresh", request=True)
+
+print(ui.findings())        # schema + grid + binding lint against the bundled catalog
+ui.save("dashboard.json")   # the composed layout, ready to push/load
+```
+
+Binding sugar: `listen=`/`when=`/`event=` build a `sync`, and `send=`/`request=`/`payload=`
+build an `action`; pass `sync=[...]`/`action={...}` (via `carterkit.bind`) for anything
+fancier. A handle comparison (`cpu > 90`) becomes a real visibility condition; `==`/`!=`
+stay normal Python, so use `.eq()`/`.neq()`. `help(carterkit.build.gauge)` prints any
+control's documentation, straight from the bundled docs.
+
+**Prefer a declarative style?** A class veneer compiles to the *same* layout — ids come
+from attribute names, tabs/groups are nested classes (great for fixed dashboards; the flat
+builder reads better for generated ones):
+
+```python
+from carterkit.declare import Screen, Tab, Connect, Gauge, Button, StatusLight
+
+class Dashboard(Screen, cols=4, rows=4):
+    relay = Connect("ws://192.168.1.50:8765", channel="home")
+    class Main(Tab, icon="gauge"):
+        cpu  = Gauge(label="CPU", min=0, max=100, span=(2, 2), listen="cpu")
+        warn = StatusLight(visible=cpu > 90)
+        refresh = Button(label="Refresh", send="refresh", request=True)
+
+Dashboard.save("dashboard.json")
+```
+
+### Dynamic groups
+
+Generate controls in `for`/`if` loops (auto-placed in the group's own grid), or mark a
+group `dynamic="event"` and replace its children live at runtime. Build that replacement
+payload with `Fragment`, then lint it against the broadcasts your server actually emits —
+catching events that never arrive, missing `children` arrays, and off-grid/invalid
+injected controls before they ship:
+
+```python
+import carterkit
+from carterkit import Fragment
+
+ui.group("Now Playing", span=(3, 4), cols=4, rows=3, dynamic="player_state")
+
+frag = Fragment(cols=4, rows=3)
+frag.label("title", text="Song", span=(1, 4))
+frag.button("play", label="Play", send="play")
+# your server broadcasts frag.payload("player_state") == {"msg_type": ..., "children": [...]}
+
+print(carterkit.format_findings(
+    carterkit.lint_dynamic_traffic(ui.layout, [frag.payload("player_state")])))
 ```
 
 Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`

carterkit-0.5.0/README.md

@@ -0,0 +1,141 @@
+# carterkit
+
+[![PyPI](https://img.shields.io/pypi/v/carterkit.svg)](https://pypi.org/project/carterkit/)
+[![Downloads](https://static.pepy.tech/badge/carterkit)](https://pepy.tech/project/carterkit)
+[![Python versions](https://img.shields.io/pypi/pyversions/carterkit.svg)](https://pypi.org/project/carterkit/)
+
+Build and drive [CAR-TER](https://carterbeaudoin.net/CAR-TER) layouts from Python.
+
+**The control docs are the library.** Every control's schema, fields, and examples
+are parsed at runtime from the ControlDocs markdown bundled inside the package — the
+exact same docs the CAR-TER app renders — so the catalog never drifts from the
+definitions.
+
+```bash
+pip install carterkit
+```
+
+## Explore the controls (zero config)
+
+```python
+import carterkit
+
+carterkit.controls()            # {type: schema} for every placeable control
+carterkit.doc("gauge")          # full parsed doc: fields, themeFields, examples
+print(carterkit.doc_markdown("gauge"))   # the rendered documentation prose
+carterkit.examples("button")    # documented example snippets
+```
+
+## Build a layout
+
+Controls are **methods on the layout**, ids are positional, tabs and groups are context
+managers, and bindings fold into kwargs. Each control method returns a **handle** you can
+use as a binding target or patch later. Unknown control types and bad enum values raise
+instead of silently shipping a broken layout:
+
+```python
+from carterkit import Layout
+
+with Layout("Dashboard", cols=4, rows=4) as ui:
+    ui.connect("ws://192.168.1.50:8765", channel="home")
+    with ui.tab("Main", icon="gauge"):
+        cpu = ui.gauge("cpu", label="CPU", min=0, max=100, span=(2, 2),
+                       listen="cpu", when={"msg_type": "metrics"})
+        ui.status_light("warn", visible=cpu > 90)      # handle → visibility condition
+        ui.button("refresh", label="Refresh", send="refresh", request=True)
+
+print(ui.findings())        # schema + grid + binding lint against the bundled catalog
+ui.save("dashboard.json")   # the composed layout, ready to push/load
+```
+
+Binding sugar: `listen=`/`when=`/`event=` build a `sync`, and `send=`/`request=`/`payload=`
+build an `action`; pass `sync=[...]`/`action={...}` (via `carterkit.bind`) for anything
+fancier. A handle comparison (`cpu > 90`) becomes a real visibility condition; `==`/`!=`
+stay normal Python, so use `.eq()`/`.neq()`. `help(carterkit.build.gauge)` prints any
+control's documentation, straight from the bundled docs.
+
+**Prefer a declarative style?** A class veneer compiles to the *same* layout — ids come
+from attribute names, tabs/groups are nested classes (great for fixed dashboards; the flat
+builder reads better for generated ones):
+
+```python
+from carterkit.declare import Screen, Tab, Connect, Gauge, Button, StatusLight
+
+class Dashboard(Screen, cols=4, rows=4):
+    relay = Connect("ws://192.168.1.50:8765", channel="home")
+    class Main(Tab, icon="gauge"):
+        cpu  = Gauge(label="CPU", min=0, max=100, span=(2, 2), listen="cpu")
+        warn = StatusLight(visible=cpu > 90)
+        refresh = Button(label="Refresh", send="refresh", request=True)
+
+Dashboard.save("dashboard.json")
+```
+
+### Dynamic groups
+
+Generate controls in `for`/`if` loops (auto-placed in the group's own grid), or mark a
+group `dynamic="event"` and replace its children live at runtime. Build that replacement
+payload with `Fragment`, then lint it against the broadcasts your server actually emits —
+catching events that never arrive, missing `children` arrays, and off-grid/invalid
+injected controls before they ship:
+
+```python
+import carterkit
+from carterkit import Fragment
+
+ui.group("Now Playing", span=(3, 4), cols=4, rows=3, dynamic="player_state")
+
+frag = Fragment(cols=4, rows=3)
+frag.label("title", text="Song", span=(1, 4))
+frag.button("play", label="Play", send="play")
+# your server broadcasts frag.payload("player_state") == {"msg_type": ..., "children": [...]}
+
+print(carterkit.format_findings(
+    carterkit.lint_dynamic_traffic(ui.layout, [frag.payload("player_state")])))
+```
+
+Prefer surgical edits? `LayoutBuffer` gives `add_control` / `update_control` / `move_control`
+over a held draft; `lay.buffer` exposes it.
+
+`infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
+`codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
+`theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
+
+## CLI
+
+```bash
+carterkit catalog                 # list every control type
+carterkit doc gauge               # print a control's documentation
+carterkit examples button         # list a control's examples (--name to print one)
+carterkit validate layout.json    # lint a layout (exit 1 on errors)
+carterkit gen layout.json         # generate a MeshSocket service stub
+carterkit relay --port 8765       # run the bundled MeshSocket relay
+```
+
+## Drive a device
+
+```python
+import asyncio
+from carterkit import CarterClient
+
+async def main():
+    async with CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                            channel="home", role="device", name="my-hub") as c:
+        c.on("toggle", lambda d: {"ok": True, **d})
+        await c.broadcast("reading", {"temp_c": 21.4})
+        await asyncio.sleep(60)
+    # leaving the `async with` disconnects automatically
+
+asyncio.run(main())
+```
+
+End-to-end encryption (ChaCha20-Poly1305 + per-session salt) is transparent when you
+pass an `e2ee_key`. Send a push to every device on a Connect+ account with
+`CarterClient.notify(...)` or the stdlib-only `carterkit.notify_http(...)`.
+
+## Built on
+
+[`meshsocket`](https://pypi.org/project/meshsocket/) — the WebSocket mesh transport.
+
+The ControlDocs are vendored from the CAR-TER app repo; refresh them with
+`scripts/sync-controldocs.sh`.

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/__init__.py

@@ -7,21 +7,24 @@ renders. So the docs never drift from the definitions; they are one and the same
 
 Quick map:
   - ``controls()`` / ``doc()`` / ``examples()`` — the docs-as-catalog surface
+  - ``Layout`` / ``Fragment`` — the flat builder: controls as methods, live handles,
+    context-manager tabs/groups (``declare.Screen`` is the declarative-class veneer)
   - ``LayoutBuffer`` — incrementally build a layout (auto-placement, dedupe)
   - ``validate_layout()`` — schema + grid lint against the bundled catalog
+  - ``lint_dynamic_traffic()`` — check ``dynamic=`` groups against observed broadcasts
   - ``infer`` / ``codegen`` / ``theming`` / ``tune`` — generate layouts, servers, themes
   - ``CarterClient`` / ``notify_http`` — connect over MeshSocket, push, send alerts
 """
 from importlib.resources import files
 from pathlib import Path
 
-from . import catalog, grid, codegen, infer, theming, tune
+from . import catalog, grid, codegen, infer, theming, tune, dynamic
 from .buffer import LayoutBuffer, BufferError
 from .validate import validate_layout as _validate_layout, format_findings
 from .client import CarterClient, notify_http, CarterNotifyError
 from . import bind
 from .controls import build, control
-from .layout import Layout
+from .layout import Layout, Fragment, Control, Condition
 
 try:
     from importlib.metadata import PackageNotFoundError, version as _pkg_version
@@ -66,12 +69,18 @@ def validate_layout(layout: dict, catalog_: dict = None) -> list:
     return _validate_layout(layout, catalog_ if catalog_ is not None else controls(include_theme=True))
 
 
+def lint_dynamic_traffic(layout: dict, observed, catalog_: dict = None) -> list:
+    """Lint a layout's `dynamic=` groups against observed broadcast payloads. Returns
+    `validate`-style findings (see `dynamic.lint_dynamic_traffic`)."""
+    return dynamic.lint_dynamic_traffic(layout, observed, catalog=catalog_)
+
+
 __all__ = [
     "__version__", "PROTOCOL_VERSION",
     "CarterClient", "notify_http", "CarterNotifyError",
     "LayoutBuffer", "BufferError",
     "controls", "doc", "doc_markdown", "examples", "validate_layout",
-    "format_findings", "controldocs_dir",
-    "build", "control", "bind", "Layout",
-    "catalog", "grid", "codegen", "infer", "theming", "tune",
+    "lint_dynamic_traffic", "format_findings", "controldocs_dir",
+    "build", "control", "bind", "Layout", "Fragment", "Control", "Condition",
+    "catalog", "grid", "codegen", "infer", "theming", "tune", "dynamic",
 ]

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/buffer.py

@@ -168,10 +168,16 @@ class LayoutBuffer:
         return ch
 
     def add_tab(self, title: str, icon: str = "square.grid.2x2",
-                columns: int = DEFAULT_COLUMNS, rows: int = DEFAULT_ROWS) -> int:
+                columns: int = DEFAULT_COLUMNS, rows: int = DEFAULT_ROWS,
+                mode: str = None, row_height: int = None) -> int:
+        grid = {"columns": columns, "rows": rows}
+        if mode is not None:
+            grid["mode"] = mode
+        if row_height is not None:
+            grid["rowHeight"] = row_height
         self.tabs.append({
             "title": title, "icon": icon,
-            "grid": {"columns": columns, "rows": rows}, "children": [],
+            "grid": grid, "children": [],
         })
         return len(self.tabs) - 1
 

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/controldocs/control-def.md

@@ -19,8 +19,8 @@ Every control — regardless of type — shares the same base fields. A control
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `span` | [rows, cols] | `[1, 1]` | Grid cells occupied (column width; **row count is advisory** — see `controlHeight`) |
-| `controlHeight` | number | — | Explicit rendered height in points. The grid lays controls out as natural-height rows, so tall controls (`map`, `list`, `graph`, `sparkline`) need this to claim vertical space. Opt-in: omit to keep the control's intrinsic height. |
+| `span` | [rowSpan, colSpan] | `[1, 1]` | Grid cells occupied. `colSpan` sets width; in a 2-D grid `rowSpan` sets height (`rowSpan × rowHeight`). Make a control bigger by spanning more cells. See [[grid-dimensions]]. |
+| `controlHeight` | number | — | **Override** the grid-derived height with an exact point value. Rarely needed: in a 2-D grid the cell (`rowSpan × rowHeight`) is the height, and in a `flow` grid shaped controls auto-size to their aspect. Use it to pin a height the grid wouldn't otherwise give. See [[grid-dimensions]]. |
 | `label` | string | — | Display label for the control |
 | `defaultValue` | bool/number/string | — | Initial value before sync |
 | `action` | [[actions\|ActionDefinition]] | — | Command fired on interaction |
@@ -40,7 +40,8 @@ Every control — regardless of type — shares the same base fields. A control
 | `tint` | string | `"#667eea"` | Hex color for accents |
 | `style` | string | varies | Style variant (per control type) |
 | `hideLabel` | bool | `false` | Suppress the label |
-| `hideBackground` | bool | `false` | Remove the glass card background |
+| `hideValue` | bool | `false` | Hide the numeric readout (e.g. a ring/gauge's center value) so the control becomes a pure compact visual that scales to fill its cell |
+| `hideBackground` | bool | `false` | Remove the glass card behind the control — it floats on the page and fills its cell. Pairs with `hideValue` for a minimal glyph |
 | `formatValue` | string | — | Number formatter for displayed values (see below) |
 
 ## Value Types
@@ -90,6 +91,7 @@ The `theme` object overrides theme values for a single control. It accepts the s
 Common override keys: `accentColor`, `foregroundColor`, `secondaryColor`, `surfacePrimary`, `borderColor`, `borderWidth`, `cornerRadius`, `controlPadding`, `fontFamily`, `fontDesign`, `labelFontSize`, `valueFontSize`. Toggle/slider/progress controls also accept `trackColor`, `trackActiveColor`, `thumbColor`, `knobColor`, etc. See each control's **Theme Overrides** table for its specific keys, and [[theming]] for the full system.
 
 ## Related
+- [[grid-dimensions]] — how `position` / `span` map to size; grid modes
 - [[group-def]] — containers for controls
 - [[layout-config]] — the top-level structure
 - [[theming]] — Theme system & live theme builder

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/controldocs/gauge.md

@@ -43,8 +43,12 @@ fields:
     description: Rotates the arc start position in degrees
   - name: arcThickness
     type: number
-    default: 8
-    description: Arc stroke width in points
+    default: auto
+    description: Arc stroke width in points. Omit to auto-scale with the gauge's size.
+  - name: hideValue
+    type: bool
+    default: false
+    description: Show just the arc — hide the center value
 themeFields:
   - name: cornerRadius
     type: number
@@ -106,10 +110,13 @@ Inherits all [[shared-properties]]. Key fields:
 | `step` | number | `1` | Used to determine decimal formatting of center value |
 | `arcAngle` | number | `180` | Arc sweep in degrees (1-360) |
 | `arcRotation` | number | `0` | Rotates the arc start position in degrees |
-| `arcThickness` | number | `8` | Arc stroke width in points |
+| `arcThickness` | number | auto | Arc stroke width in points. Omit to auto-scale with the gauge's size; set for an absolute width |
+| `hideValue` | bool | `false` | Show just the arc — hide the center value (pairs with `hideBackground` for a compact glyph) |
 
 > **Note:** `gaugeStyle` is a shorthand alias. `"half"` sets `arcAngle: 180` and `"full"` sets `arcAngle: 360`. When `arcAngle` is set explicitly, it takes precedence over `gaugeStyle`.
 
+> **Sizing:** the arc, stroke, and center value all scale to the gauge's size. A `half` gauge is wide (2:1); a `full` gauge is square (1:1) — give it ~3 `rowSpan` in a 2-D grid so it reads square. See [[grid-dimensions]].
+
 ## Gauge Segments
 
 Color zones that change based on the current value:

carterkit-0.5.0/carterkit/controldocs/grid-dimensions.md

@@ -0,0 +1,93 @@
+---
+type: grid-dimensions
+label: Grid Dimensions
+icon: square.grid.3x3
+category: models
+fields:
+  - name: columns
+    type: number
+    description: Number of columns the grid is divided into (required)
+  - name: rows
+    type: number
+    description: Number of rows the grid is divided into (required)
+  - name: mode
+    type: string
+    description: '"grid" (2-D, default) or "flow" (legacy row-banded)'
+  - name: rowHeight
+    type: number
+    description: Points per row-unit in 2-D mode (default 56)
+---
+
+Every tab and every [[group-def|group]] lays its children out on a **grid** of
+`columns` × `rows`. A child declares where it sits with `position: [row, col]`
+and how many cells it covers with `span: [rowSpan, colSpan]` (see [[control-def]]).
+
+```json
+"grid": { "columns": 4, "rows": 6 }
+```
+
+## Modes
+
+| `mode` | Layout | Best for |
+|--------|--------|----------|
+| `"grid"` *(default)* | **True 2-D.** Each child occupies a real `row × col` rectangle. Columns divide the width evenly; rows are a fixed `rowHeight` unit. A child can span **both** axes, so a tall control can sit **beside** two stacked shorter ones (masonry / L-shapes). | Dashboards and mixed screens — gauges, rings, inputs, maps together. |
+| `"flow"` | **Legacy row-banded.** Children are grouped by their row index into horizontal bands; `colSpan` sets proportional width but heights are natural (or `controlHeight`). `rowSpan` is ignored. | Full-page content (a single `map` / `chat` / `cardList` filling the tab) and pure forms where natural heights read best. |
+
+`mode` is optional — omit it for the default 2-D grid. Set `"flow"` to opt a tab
+or group out.
+
+```json
+"grid": { "columns": 4, "rows": 8, "mode": "flow" }
+```
+
+## How spans map to size
+
+| | 2-D (`"grid"`) | `"flow"` |
+|--|----------------|----------|
+| **`colSpan`** (width) | `colSpan / columns` of the row width | `colSpan / columns` of the row width |
+| **`rowSpan`** (height) | `rowSpan × rowHeight` points | ignored — height is natural / `controlHeight` |
+
+So in 2-D a 1×1 cell is genuinely small, and you make a control bigger by spanning
+more cells. Visual controls scale all of their internals (stroke, glyph, font) to
+the cell they're given — a small ring is tight and legible, a large ring is bold.
+
+## `rowHeight`
+
+The height of one row-unit, in points (2-D mode only; default **56**). One unit is
+a comfortable input row, so:
+
+- inputs (`slider`, `toggle`, `segmentedControl`, …) sit in **1 row**,
+- a square control (`progressRing`, full `gauge`) wants **~3 rows** to read square,
+- tall content (`map`, `list`, `graph`, `image`) spans **as many rows as you give it**.
+
+```json
+"grid": { "columns": 4, "rows": 10, "rowHeight": 64 }
+```
+
+## Sizing a control
+
+You usually don't set a height at all — in 2-D the cell (`rowSpan × rowHeight`)
+*is* the height, and in flow shaped controls auto-size to their natural aspect.
+`controlHeight` (see [[control-def]]) is an **override** for the rare case you want
+an exact point height regardless of the grid.
+
+## Example — a 2-D dashboard with an L-shape
+
+```json
+{
+  "grid": { "columns": 4, "rows": 5 },
+  "children": [
+    { "type": "progressRing", "id": "cpu", "position": [0, 0], "span": [3, 2], "label": "CPU" },
+    { "type": "gauge",        "id": "mem", "position": [0, 2], "span": [2, 2], "label": "Memory" },
+    { "type": "statusLight",  "id": "net", "position": [2, 2], "span": [1, 2], "label": "Uplink" }
+  ]
+}
+```
+
+The CPU ring is a tall 2×2-plus block on the left; Memory and the Uplink light
+stack to its right — placement that the flow renderer can't express.
+
+## Related
+- [[control-def]] — `position`, `span`, `controlHeight`, `hideValue`, `hideBackground`
+- [[group-def]] — a group has its own grid (and its own `mode`)
+- [[layout-config]] — the top-level structure

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/controldocs/index.md

@@ -125,6 +125,11 @@ A layout JSON file has this shape:
 }
 ```
 
+Each tab lays its children out on a **2-D grid** — a control's `position` and `span`
+place it in a `row × col` rectangle, so a tall control can sit beside two stacked
+shorter ones. Set a grid's `mode` to `"flow"` for the simpler row-banded layout
+(full-page content, plain forms). See [[grid-dimensions]].
+
 Tap any node in the graph to explore the full documentation for each control type, system feature, and data model.
 
 ---
@@ -133,9 +138,9 @@ Tap any node in the graph to explore the full documentation for each control typ
 
 1. **Explore the docs** — tap nodes in the graph to learn about each control
 2. **Write a layout** — create a JSON file following the [[layout-config]] schema
-3. **Run a server** — start a MeshSocket server to handle events
+3. **Run a server** — drive your layout from Python with `pip install carterkit`, or
+   speak the MeshSocket protocol directly from any language
 4. **Connect** — load your layout and watch it come alive
 
-The full MeshSocket server implementation and protocol documentation is available on GitHub:
-
-[github.com/carterbeaudoin/MeshSocket](https://github.com/carterbeaudoin/MeshSocket)
+Full developer docs — building servers, the wire protocol, and the `carterkit`
+library — live at **carterbeaudoin.net/CAR-TER**.

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/controldocs/map.md

@@ -71,7 +71,7 @@ Inherits all [[shared-properties]]. Key fields:
 | `mapStyle` | string | `"standard"` | `"standard"`, `"satellite"`, `"hybrid"` |
 | `mapInteractive` | bool | `true` | Allow user pan/zoom |
 | `mapZoom` | number | `0.01` | Default coordinate span in degrees |
-| `controlHeight` | number | `120` (min) | Rendered height in points. The map is only ~120pt tall by default; set this (e.g. `300`) for a full-screen-feel map. See [[control-def]]. |
+| `controlHeight` | number | `120` (min) | In a 2-D grid, give the map more `rowSpan` for a taller map (height = `rowSpan × rowHeight`). In a `flow` grid it is ~120pt by default — set this (e.g. `300`) for a full-screen-feel map. See [[grid-dimensions]]. |
 | `label` | string | — | Header label above the map |
 | `tint` | string | `"#667eea"` | Center point marker color |
 

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/controldocs/privacy.md

@@ -49,4 +49,4 @@ We may update this policy; the effective date above reflects the latest version.
 
 ## Contact
 
-Questions or data requests: support@carterbeaudoin.com
+Questions or data requests: support@carterbeaudoin.net

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/controldocs/progress-ring.md

@@ -28,6 +28,10 @@ fields:
   - name: icon
     type: string
     description: SF Symbol in center (ring only)
+  - name: hideValue
+    type: bool
+    default: false
+    description: Show just the arc — hide the center value
 themeFields:
   - name: cornerRadius
     type: number
@@ -85,11 +89,15 @@ Inherits all [[shared-properties]]. Key fields:
 | `tint` | string | `"#667eea"` | Fill color |
 | `label` | string | — | Center text (ring) or header text (bar) |
 | `icon` | string | — | SF Symbol in center (ring only) |
+| `hideValue` | bool | `false` | Show just the arc — hide the center value (pairs with `hideBackground` for a compact glyph) |
 
 ## Styles
 
 ### `"ring"` (default)
-Circular progress ring with percentage and optional label/icon in the center. Square aspect ratio.
+Circular progress ring with percentage and optional label/icon in the center. The
+stroke, number, icon, and label all scale to the ring's size, so a small cell stays
+tight and a large one reads bold. Square aspect (1:1) — give it ~3 `rowSpan` in a
+2-D grid. Set `hideValue` (and `hideBackground`) for a bare ring glyph. See [[grid-dimensions]].
 
 ### `"bar"`
 Linear progress bar (thin horizontal bar). Header shows label and percentage.

{carterkit-0.3.1 → carterkit-0.5.0}/carterkit/controldocs/terms.md

@@ -37,4 +37,4 @@ Your use is also governed by our **Privacy Policy** at https://carterbeaudoin.ne
 
 ## 6. Changes and contact
 
-We may update these Terms; the effective date reflects the latest version. Questions: support@carterbeaudoin.com
+We may update these Terms; the effective date reflects the latest version. Questions: support@carterbeaudoin.net