carterkit 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.4.0
+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

{carterkit-0.4.0 → 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.4.0 → 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.4.0 → 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.4.0 → 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.
 
 ---

{carterkit-0.4.0 → 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.4.0 → 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.4.0 → 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.4.0 → 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

{carterkit-0.4.0 → carterkit-0.5.0}/carterkit/layout.py

@@ -164,14 +164,20 @@ class _GridScope:
 
     def group(self, label=None, *, id=None, span=None, position=None, cols: int = 4,
               rows: int = 4, dynamic=None, visible=None, pulse=None,
-              hide_background=None) -> "GroupHandle":
+              hide_background=None, mode: str = None, row_height: int = None) -> "GroupHandle":
         """Add a group container and return a handle you can `with`-enter to fill.
 
         `dynamic="event"` makes the group's children runtime-injectable (replaced by a
-        broadcast with matching `msg_type` — build that payload with :class:`Fragment`)."""
+        broadcast with matching `msg_type` — build that payload with :class:`Fragment`).
+        `mode="flow"` opts this group out of the default 2-D grid; `row_height` sets the
+        2-D row unit in points (default 56)."""
         gid = self._owner._unique_id(id or "group")
-        g: dict = {"type": "group", "id": gid,
-                   "grid": {"columns": cols, "rows": rows}, "children": []}
+        grid: dict = {"columns": cols, "rows": rows}
+        if mode is not None:
+            grid["mode"] = mode
+        if row_height is not None:
+            grid["rowHeight"] = row_height
+        g: dict = {"type": "group", "id": gid, "grid": grid, "children": []}
         if label is not None:
             g["label"] = label
         if dynamic is not None:
@@ -304,19 +310,27 @@ class Layout:
         return self
 
     def tab(self, title: str, *, icon: str = "square.grid.2x2",
-            cols: int = None, rows: int = 6, columns: int = None) -> TabHandle:
+            cols: int = None, rows: int = 6, columns: int = None,
+            mode: str = None, row_height: int = None) -> TabHandle:
         """Start a tab and make it current. First call configures the default tab;
         later calls append. `with ui.tab(...)` scopes controls to it; the flat form
-        ``ui.tab("Main"); ui.gauge(...)`` works too."""
+        ``ui.tab("Main"); ui.gauge(...)`` works too. `mode="flow"` opts the tab out of
+        the default 2-D grid; `row_height` sets the 2-D row unit (points, default 56)."""
         cols = cols if cols is not None else (columns if columns is not None else 4)
+        grid = {"columns": cols, "rows": rows}
+        if mode is not None:
+            grid["mode"] = mode
+        if row_height is not None:
+            grid["rowHeight"] = row_height
         if not self._first_tab_used:
             t = self._buf.tabs[0]
             t["title"], t["icon"] = title, icon
-            t["grid"] = {"columns": cols, "rows": rows}
+            t["grid"] = grid
             self._tab_index = 0
             self._first_tab_used = True
         else:
-            self._tab_index = self._buf.add_tab(title, icon=icon, columns=cols, rows=rows)
+            self._tab_index = self._buf.add_tab(title, icon=icon, columns=cols, rows=rows,
+                                                mode=mode, row_height=row_height)
         self._scope = self._scope_for_tab(self._tab_index)
         return TabHandle(self, self._scope, self._tab_index)
 

{carterkit-0.4.0 → carterkit-0.5.0}/carterkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.4.0
+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

{carterkit-0.4.0 → carterkit-0.5.0}/carterkit.egg-info/SOURCES.txt

@@ -41,6 +41,7 @@ carterkit/controldocs/divider.md
 carterkit/controldocs/flip-card.md
 carterkit/controldocs/gauge.md
 carterkit/controldocs/graph.md
+carterkit/controldocs/grid-dimensions.md
 carterkit/controldocs/group-def.md
 carterkit/controldocs/haptics.md
 carterkit/controldocs/image.md

{carterkit-0.4.0 → carterkit-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "carterkit"
-version = "0.4.0"
+version = "0.5.0"
 description = "Build and drive CAR-TER layouts from Python — the control docs are the library."
 readme = "README.md"
 requires-python = ">=3.10"