pgwidgets-js 0.3.0__tar.gz → 0.3.2__tar.gz

{pgwidgets_js-0.3.0 → pgwidgets_js-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgwidgets-js
-Version: 0.3.0
+Version: 0.3.2
 Summary: pgwidgets JavaScript widget library — static assets for use with Python servers
 Author: PGWidgets Developers
 License: BSD-3-Clause

{pgwidgets_js-0.3.0 → pgwidgets_js-0.3.2}/docs/WhatsNew.rst

@@ -1,6 +1,286 @@
 What's New
 ==========
 
+Recent changes — since ``v0.3.0``
+---------------------------------
+
+Containers report their children: ``get_children``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+More widgets are now treated as containers and expose the full
+container method set (``get_children`` / ``num_children`` /
+``remove`` / ``remove_widget`` / ``remove_all``):
+
+* ``Frame``, ``Expander``, ``TopLevel`` and ``Page`` -- single-child
+  containers (one child via ``set_widget``); ``get_children()``
+  returns a 0- or 1-element list.
+* ``Menu``, ``MenuBar`` and ``ToolBar`` -- these now extend
+  ``ContainerWidget`` and route their item additions
+  (``add_name`` / ``add_menu`` / ``add_action`` / ``add_widget``)
+  through ``add_child``, so the menu actions / submenus / toolbar
+  items they hold are reported by ``get_children()``.  Separators
+  and spacers (which are not widgets) are excluded.
+
+This matches the behaviour generic code expects of any container.
+
+ScrollArea: content fills the viewport
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The scroll content wrapper is now a flex column.  A child that opts
+to fill (e.g. via ``set_expanding`` or a ``Box`` stretch factor) now
+fills the viewport when its content is smaller, while still growing
+and scrolling when the content exceeds it.  A child with no expand
+policy keeps its natural size (top-aligned), exactly as before.
+
+TreeView / TableView: ``set_row_spacing`` / ``set_column_spacing``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Two new methods set the vertical (row) and horizontal (column) cell
+padding, driving the ``--tv-row-pad`` / ``--tv-col-pad`` CSS variables
+that ``.treeview-cell`` consumes (defaults ``2px`` / ``6px``).
+``set_row_spacing`` additionally relaxes the fixed row ``min-height``
+(``--tv-row-minheight``) so rows can tighten to their content +
+padding instead of being held at the 24px floor.
+
+``open-url``: open a link in the user's browser
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A new remote-protocol message type, ``open-url``, opens a URL in the
+connected browser (``window.open(url, "_blank", "noopener")``) -- so
+host-side code can open a link in the *user's* browser rather than on
+the machine running Python.  (Note: a popup blocker may suppress it
+if the user-activation from the originating click has lapsed.)
+
+ProgressBar: visible height inside a vertical box
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The progress bar now carries a ``min-height`` so it stays visible
+when packed in a vertical ``Box``.  (Its fill / label are absolutely
+positioned, and a vertical ``Box`` forces inline ``height: auto`` on
+children, which previously collapsed the bar to zero height --
+leaving only the border line.)
+
+Custom fonts: ``register-font`` / ``set-default-font``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Two new remote-protocol message types let the Python side push
+custom font files to the browser and apply a document-wide
+default font.
+
+* ``register-font`` -- the JS handler creates a ``FontFace``,
+  awaits its ``load()``, and adds it to ``document.fonts``,
+  after which any widget ``set_font(family, ...)`` resolves
+  against it.  The accompanying ``url`` is resolved against
+  ``window.location.href`` so the same path works under the
+  built-in HTTP server, Flask / nginx, and pyodide.
+* ``set-default-font`` -- manages a single
+  ``<style id="pg-default-font">`` element on ``<head>`` that
+  writes ``--pg-default-font-{family,size,weight,style}`` CSS
+  variables on ``:root``.  The base ``body`` rule consumes
+  those variables with safe fallbacks
+  (``sans-serif`` / ``13px`` / ``normal`` / ``normal``), so
+  apps that never opt in see no behavioural change.  Per-
+  widget ``set_font(...)`` still wins via inline-style
+  specificity.
+
+Weight / style normalisation in the JS handler translates
+descriptive TTF metadata names -- ``thin``, ``light``,
+``medium``, ``semibold``, ``extrabold``, ``black``, ``heavy``,
+etc. -- to the numeric CSS values per the CSS Fonts spec, so
+fonts shipped with descriptive weight names load without
+raising ``Invalid font descriptor`` errors.  Numeric strings
+and valid CSS keywords pass through unchanged.
+
+See :ref:`custom-fonts` for the matching Python-side API.
+
+TreeView: column-boundary alignment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Three related fixes keep the header columns pinned to the body
+columns in every case:
+
+* ``_syncScrollbars`` writes ``this._header.style.width =
+  this._body.scrollWidth`` so ``1fr`` grid units resolve to
+  identical pixel widths in the header and body grids -- a
+  body grown to ``max-content`` by wide row content no longer
+  drifts wider than the header.
+* ``_gridTemplate`` wraps every ``fr`` track in
+  ``minmax(0, fr)``.  Without it a single widget cell whose
+  content can't shrink (a ``<button>Reset</button>`` or
+  ``<select>``) forces its column wider than the matching
+  empty-content header track; ``minmax(0, fr)`` lets the
+  ``fr`` distribution dominate.  Oversize content is clipped
+  by the cell's own ``overflow: hidden``.
+* ``_setupColumnResize`` lowers the minimum drag width from
+  30 px to 5 px so genuinely small icon / checkbox columns
+  (``colwidth: 10`` and similar) can be resized instead of
+  inflating to 30 the moment a drag starts.
+
+Image (animation-frame): wrapper div
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Animation-frame ``Image`` mode wraps its canvas in a
+``<div class="image-widget">`` and positions the canvas
+``absolute; inset: 0; width: 100%; height: 100%``.  The wrapper
+sits in the layout chain like any plain block, and absolutely-
+positioned children contribute zero to their parent's
+auto-resolved size -- so writing ``canvas.width`` /
+``canvas.height`` in the resize callback (which the browser
+mirrors back as an ``aspect-ratio: auto W/H`` presentational
+hint) can no longer feed back into layout.  Resolves the
+runaway-vertical-growth feedback loop that ``contain: size`` on
+a bare canvas couldn't fully gate.
+
+The wrapper has no width/height of its own -- callers must
+give it size via ``set_expanding(True, True)``, packing with
+``stretch > 0``, or ``resize(w, h)``.
+
+Box / Widget: respect user-set min sizes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Box._applyBoxChildSizing`` (in the ``stretch > 0`` and
+``mainExpand`` branches) and ``Widget.set_expanding`` were
+both writing ``min-width: 0`` / ``min-height: 0`` unconditionally
+to override the browser's default ``min: auto`` on flex items.
+Either of them running second silently erased a floor declared
+via ``set_min_size``.  Both call sites now guard with
+``if (!s.minWidth) s.minWidth = '0'`` so user-set mins survive
+regardless of call order.
+
+TreeView / TableView: widget-typed cells
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Column descriptors gained an optional ``widget`` field that
+swaps a column's plain-text cells for a real DOM input element:
+
+* ``"checkbox"`` -- ``<input type="checkbox">`` bound to a
+  boolean cell value;
+* ``"combobox"`` -- ``<select>`` populated from a ``choices``
+  array;
+* ``"progress"`` -- ``<progress>`` driven by ``min`` / ``max``
+  (read-only);
+* ``"button"`` -- ``<button>`` whose label is the cell value
+  (or the column's ``text`` fallback).
+
+Editable widget cells fire ``cell_edited(widget, path, col_key,
+old, new)``; buttons fire a new ``cell_action(widget,
+row_values, col_key)`` callback.  Two more column-descriptor
+keys gate the per-row widget by row-dict field name:
+``enabled_key`` (greys the widget out when the named field is
+falsy) and ``visible_key`` (suppresses the widget entirely on
+that row -- the cell stays empty).
+
+.. code-block:: javascript
+
+   table.set_columns([
+       {label: "Name", key: "NAME", type: "string"},
+       {label: "Done", key: "DONE", type: "bool",
+        widget: "checkbox", enabled_key: "CAN_EDIT"},
+       {label: "",     key: "GO",   type: "string",
+        widget: "button", text: "Open",
+        visible_key: "OPENABLE"},
+   ]);
+
+Cell / row / column / table colour overrides
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Four new override layers paint cells without touching the
+underlying data: ``set_cell_color(path, col_key, fg, bg, bold)``,
+``set_row_color(path, fg, bg, bold)``, ``set_column_color(col_key,
+fg, bg, bold)``, and ``set_table_color(fg, bg, bold)``.
+Specificity cascades cell → row → column → table per-channel,
+so a row-level fg + column-level bg compose into the same
+cell.  Each method also accepts an optional ``bold`` argument
+that toggles the cell font weight.
+
+Matching ``clear_*_color`` helpers and ``clear_all_colors()``
+drop overrides at any layer.
+
+Cell-level selection and clipboard
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TreeView / TableView gained two new ``selection_mode`` values --
+``"single-cell"`` and ``"multiple-cell"`` -- that let the user
+select individual cells rather than whole rows.  Cell selections
+fire a new ``cell_selected`` callback with the list of selected
+``{path, col_key, value}`` cells.
+
+Widget-level Ctrl/Cmd+C/X/V keyboard handlers feed three new
+callbacks: ``copy``, ``cut``, ``paste``.  The
+``copy_selection`` / ``cut_selection`` / ``paste_selection``
+methods do the same programmatically.  Cell-mode cuts emit a
+TSV payload built from the selected cells; row mode emits the
+whole row.
+
+``activated`` callback now reports the clicked column
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``activated`` callback signature gained a 4th argument:
+``(widget, values, path, col_key)``.  Handlers that destructure
+the first three keep working; new code can branch on which
+column the user double-clicked.
+
+Widget: ``set_bg`` + Label: ``set_valign``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Two small style helpers:
+
+* ``Widget.set_bg(color)`` on the base class -- generic
+  background-colour setter, accepts a CSS string or ``null``
+  to clear.  Works on transparent containers (Box / Grid /
+  ScrollArea) too.
+* ``Label.set_valign(align)`` -- ``"top"`` / ``"center"`` /
+  ``"bottom"`` vertical placement of the label text within
+  whatever vertical space the parent allocates.  Only visible
+  when the label is given more height than its text needs.
+
+Box: ``set_align`` (cross-axis)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Boxes (and the ``HBox`` / ``VBox`` shortcuts) gained a single
+orientation-aware ``set_align(align)`` method controlling the
+cross-axis placement of children:
+
+* horizontal box → ``"top"`` / ``"center"`` / ``"bottom"``;
+* vertical box   → ``"left"`` / ``"center"`` / ``"right"``.
+
+Mismatched names raise.  Maps to flex ``align-items`` on the
+box element.
+
+TableView: positional row API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``TableView`` gained an explicit positional-row API so callers
+that maintain row data as positional arrays (one common
+cross-backend pattern) don't have to wrap every row in a dict:
+
+* ``set_data(rows)`` now accepts either a list of dicts
+  (preferred, keyed by column key) *or* a list of positional
+  arrays mapped to columns in order.
+* ``insert_row(index, values)`` -- new method.  ``values`` is
+  a dict or an array; ``index`` is the 0-based visible
+  position, out-of-range clamps to append.  Returns the new
+  row's path so the caller can address it afterwards.
+* ``append_row(values)`` is the index-at-end shortcut.
+
+The row-key generator stays internal (``row0``, ``row1`` ...);
+sort order, selection, and the per-cell colour overrides all
+follow rows by key rather than by visible index, so positional
+inserts compose with the existing higher-level APIs.
+
+Other improvements
+~~~~~~~~~~~~~~~~~~
+
+* TreeView: fix two cell-editing / rendering bugs.  The per-
+  cell ``dblclick`` handler captured the loop counter ``i``
+  from the *outer* scope -- which had already advanced past
+  the row by the time the click fired -- and a sibling
+  rendering path miscomputed the row index when columns were
+  hidden.  Both surfaced when wiring inline editing through
+  cross-backend table widgets.
+
+----
+
 Recent changes — since ``v0.2.3``
 ---------------------------------
 

{pgwidgets_js-0.3.0 → pgwidgets_js-0.3.2}/docs/styling.rst

@@ -132,6 +132,16 @@ override CSS when called:
      - CSS Properties Affected
    * - ``set_color(bg, fg)``
      - ``background-color``, ``color``
+   * - ``set_bg(color)``
+     - ``background-color`` (base-class helper; ``null`` clears
+       the override)
+   * - ``Label.set_valign(align)``
+     - ``display: flex; flex-direction: column; justify-content:
+       flex-start | center | flex-end`` -- vertical placement
+       of the label text
+   * - ``Box.set_align(align)``
+     - ``align-items`` (cross-axis alignment of Box children;
+       orientation-aware)
    * - ``set_font(family, size, weight, style)``
      - ``font-family``, ``font-size``, ``font-weight``, ``font-style``
    * - ``set_border_width(w)``
@@ -167,6 +177,110 @@ same property -- use CSS for global theming and programmatic methods for
 dynamic per-widget changes.
 
 
+.. _custom-fonts:
+
+Custom Fonts
+------------
+
+Two new application-level methods (added since v0.3.0) let the
+Python side push custom font files to the browser and apply a
+document-wide default font.  The mechanism is the
+``FontFace`` API + ``document.fonts.add()`` plus a small
+managed ``<style>`` element that writes CSS variables on
+``:root``.
+
+Registering a font
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   app.register_font('Roboto', '/path/to/Roboto-Regular.ttf')
+   app.register_font('Roboto', '/path/to/Roboto-Bold.ttf',
+                     weight='bold')
+   app.register_font('Roboto', '/path/to/Roboto-Italic.ttf',
+                     style='italic')
+
+* ``family`` is the CSS ``font-family`` name you'll reference
+  from widget ``set_font(...)`` calls or from CSS.  Names are
+  passed through verbatim -- pick any case convention and stay
+  consistent.
+* ``source`` is a path (``str`` or ``os.PathLike``) or raw
+  ``bytes`` (e.g. ``font_path.read_bytes()`` or an in-memory
+  font from another library).
+* ``weight`` accepts CSS keywords (``'normal'``, ``'bold'``,
+  ``'bolder'``, ``'lighter'``) or numeric strings (``'100'``
+  through ``'1000'``).  The JS handler also translates common
+  TTF metadata names like ``thin``, ``light``, ``medium``,
+  ``semibold``, ``extrabold``, ``black``, ``heavy``, etc. to
+  their numeric equivalents per the CSS Fonts spec, so passing
+  weights straight from a font registry usually Just Works.
+* ``style`` accepts ``'normal'``, ``'italic'``, or
+  ``'oblique'`` (synonyms like ``'roman'`` / ``'slanted'`` get
+  normalised too).
+
+Multiple registrations against the same ``family`` with
+different ``weight`` / ``style`` combine into a single CSS
+font-family with multiple faces -- exactly the same way an
+``@font-face`` author would express it.
+
+The bytes are served via the built-in HTTP server at
+``/_pgwidgets/font/<id>`` with a long ``Cache-Control:
+immutable`` header.  When pgwidgets is embedded behind a Flask
+/ nginx stack, the route is served from the same Python process
+so it passes through naturally; under pyodide the URL is
+relative to ``window.location.href``.
+
+Default font
+~~~~~~~~~~~~
+
+.. code-block:: python
+
+   app.set_default_font('Roboto', size=13)
+
+Writes ``--pg-default-font-family``,
+``--pg-default-font-size``, ``--pg-default-font-weight`` and
+``--pg-default-font-style`` CSS variables on ``:root`` (via a
+managed ``<style id="pg-default-font">`` element).  The base
+widget stylesheet consumes them on ``body``::
+
+   body {
+       font-family: var(--pg-default-font-family, sans-serif);
+       font-size:   var(--pg-default-font-size,   13px);
+       font-weight: var(--pg-default-font-weight, normal);
+       font-style:  var(--pg-default-font-style,  normal);
+   }
+
+Anything that doesn't set a font of its own inherits the
+default.  Per-widget ``set_font(...)`` still wins via
+inline-style specificity, and the fallback values in the
+``var(...)`` calls are what you get when ``set_default_font``
+is never called -- so existing apps see no behavioural change.
+
+Pass ``family=None`` to clear the default and fall back to the
+stylesheet values.
+
+Reconstruction
+~~~~~~~~~~~~~~
+
+Font registrations are replayed to every new and reconnecting
+session before ``on_connect`` / ``reconstruct`` runs, so a
+widget reconstructed with ``set_font(family, ...)`` always
+finds the face already declared.
+
+Caveats
+~~~~~~~
+
+* Browsers may render fallback text in the brief window
+  between the ``register-font`` message arriving and
+  ``face.load()`` resolving (standard FOUT behaviour).  For
+  most apps this flash is invisible; if it matters you can
+  ``await document.fonts.ready`` in your bootstrap.
+* The bytes are kept in memory on the Python side for the
+  lifetime of the ``Application``.  A 200 KiB TTF is fine; a
+  4 MiB color-emoji set might warrant chunking or on-disk
+  caching.
+
+
 Handling CSS Conflicts with Other Libraries
 -------------------------------------------
 

{pgwidgets_js-0.3.0 → pgwidgets_js-0.3.2}/docs/widgets/display.rst

@@ -271,6 +271,10 @@ matter how the visible tree is sorted.
 selection_mode, alternate_row_colors, show_grid, show_row_numbers,
 sortable, allow_text_selection})``
 
+``selection_mode`` is one of ``"single"`` / ``"multiple"`` (rows)
+or ``"single-cell"`` / ``"multiple-cell"`` (cells).  See
+"Cell-level selection" below.
+
 **Column descriptors:** each column is a string (label only) or an
 object with the following keys:
 
@@ -288,6 +292,22 @@ object with the following keys:
 - ``editable`` -- whether cells in the column can be edited via
   double-click.
 - ``icon_size`` -- pixel size for icon columns (default 16).
+- ``colwidth`` -- initial column width.  Numbers are pixels;
+  strings pass through as CSS grid track values (e.g.
+  ``"10em"``, ``"1fr"``).  Default is ``"1fr"``.
+- ``widget`` -- one of ``"checkbox"`` / ``"combobox"`` /
+  ``"progress"`` / ``"button"``.  Replaces the column's
+  plain-text cells with a real DOM input.  See "Widget cells"
+  below.
+- ``choices`` -- ``Array`` of option strings (combobox only).
+- ``min`` / ``max`` -- numeric bounds (progress only).
+- ``text`` -- default button label when the row value is
+  ``null`` (button only).
+- ``enabled_key`` -- name of a row-dict field whose truthiness
+  gates the embedded widget's enabled state per row.
+- ``visible_key`` -- name of a row-dict field whose truthiness
+  gates whether the widget appears on a given row.  When
+  falsy, the cell stays empty.
 
 **Tree shape (set_tree):**
 
@@ -376,10 +396,32 @@ supplies no value for it, so most interiors need no
      - Set column width.
    * - ``set_optimal_column_widths()``
      - Auto-size all columns.
+   * - ``set_row_spacing(px)`` / ``set_column_spacing(px)``
+     - Set the vertical (row) / horizontal (column) cell padding in
+       pixels.  ``set_row_spacing(0)`` also relaxes the row min-height
+       floor, giving tight rows.
    * - ``set_show_grid(tf)`` / ``set_show_row_numbers(tf)`` / ``set_sortable(tf)``
      - Toggle grid lines, row numbers, and click-to-sort.
    * - ``set_column_editable(col_key, tf)``
      - Make a column editable.
+   * - ``set_cell_color(path, col_key, fg, bg, bold)`` /
+       ``set_row_color(path, fg, bg, bold)`` /
+       ``set_column_color(col_key, fg, bg, bold)`` /
+       ``set_table_color(fg, bg, bold)``
+     - Per-cell / row / column / table style overrides.  Each
+       channel cascades cell → row → column → table.  See
+       "Colour overrides" below.
+   * - ``clear_cell_color`` / ``clear_row_color`` /
+       ``clear_column_color`` / ``clear_all_colors``
+     - Drop overrides at the matching layer.
+   * - ``select_cell(path, col_key, state)`` /
+       ``select_cells(cells, state)`` /
+       ``clear_cell_selection()``
+     - Cell-mode selection API.  ``cells`` is an array of
+       ``{path, col_key}`` objects.
+   * - ``copy_selection()`` / ``cut_selection()`` /
+       ``paste_selection(tsv)``
+     - Programmatic equivalents of Ctrl/Cmd+C/X/V.
 
 **Auto-spanning:** within a row, a column whose key is missing is
 "absent" and the preceding present cell extends across it via CSS
@@ -390,15 +432,58 @@ across the row.
 
 **Callbacks:**
 
-- ``activated`` -- handler signature ``(widget, values, path)``;
-  fires on row double-click or Enter.
+- ``activated`` -- handler signature ``(widget, values, path,
+  col_key)``; fires on row double-click or Enter.  ``col_key``
+  is the column the click landed on (``null`` for
+  keyboard-triggered activation).
 - ``selected`` -- selection changed; handler receives an array of
   ``{path, values}`` objects.
 - ``expanded`` / ``collapsed`` -- handler ``(widget, values, path)``.
 - ``cell_edited`` -- ``(widget, path, col_key, oldValue, newValue)``.
+- ``cell_selected`` -- cell-mode selection changed; handler
+  receives ``(widget, cells)`` where each cell is
+  ``{path, col_key, value}``.
+- ``cell_action`` -- ``(widget, row_values, col_key)``; fires
+  when the user clicks a ``widget: "button"`` cell.
+- ``copy`` / ``cut`` / ``paste`` -- ``(widget, tsv)``; fire from
+  Ctrl/Cmd+C/X/V and from the programmatic helpers.
 - ``sorted`` -- ``(widget, col_key, ascending)``.
 - ``scrolled`` -- ``(widget, h_pct, v_pct)``.
 
+**Widget cells.** A column with ``widget`` set hosts a real
+DOM input per cell:
+
+* ``"checkbox"`` -- bound to a boolean cell value; toggling
+  fires ``cell_edited``.
+* ``"combobox"`` -- ``<select>`` populated from ``choices``;
+  changing fires ``cell_edited``.
+* ``"progress"`` -- read-only ``<progress>`` driven by
+  ``min`` / ``max`` and the numeric cell value.
+* ``"button"`` -- ``<button>`` whose label is the cell value
+  (or the column's ``text`` fallback when null); clicking
+  fires ``cell_action``.
+
+``enabled_key`` and ``visible_key`` name row-dict fields that
+gate the per-row widget.  An empty row value of ``null`` /
+``false`` on a button column suppresses that row's button if
+``visible_key`` is also unset.
+
+**Colour overrides.** Each of the four ``set_*_color`` methods
+takes ``fg`` (text), ``bg`` (background), and ``bold``.  All
+three are optional; passing all-null clears that layer's
+override.  Resolved style cascades per-channel cell → row →
+column → table, so a row-level fg can compose with a
+column-level bg.
+
+**Cell-level selection.** Setting ``selection_mode`` to
+``"single-cell"`` or ``"multiple-cell"`` switches the
+behaviour from row selection to cell selection.  Selection
+state is reported via the new ``cell_selected`` callback;
+``select_cell`` / ``select_cells`` / ``clear_cell_selection``
+mutate it programmatically.  The widget-level
+``copy_selection`` / ``cut_selection`` honour cell-mode and
+emit a TSV payload.
+
 .. code-block:: javascript
 
    let tree = new Widgets.TreeView({
@@ -456,11 +541,27 @@ dicts (preferred) or a list of positional arrays:
    table.append_row({NAME: "Carol", DEPT: "Sales", SALARY: 71000});
    table.sort_by_column("SALARY", false);  // descending
 
-**Callbacks:**
-
-- ``activated`` -- ``(widget, values, path)``; fires on row
-  double-click or Enter.
-- ``selected`` -- ``(widget, items)`` where each item is
-  ``{path, values}``.
-- ``cell_edited`` -- ``(widget, path, col_key, oldValue, newValue)``.
-- ``sorted``, ``scrolled`` -- as for TreeView.
+**Callbacks:** identical to TreeView, including the new
+``activated`` 4-arg signature with ``col_key``, the
+``cell_selected`` / ``cell_action`` / ``copy`` / ``cut`` /
+``paste`` callbacks, and the per-cell ``cell_edited``
+signature.
+
+TableView ``set_columns`` accepts the same column descriptor
+fields as TreeView, including ``widget`` / ``choices`` /
+``min`` / ``max`` / ``text`` / ``enabled_key`` /
+``visible_key`` / ``colwidth``.  Colour overrides
+(``set_*_color`` / ``clear_*_color``) work identically.
+
+For per-row Mute checkbox + Reset button -- the canonical
+"widget cells" use case -- declare two columns::
+
+    table.set_columns([
+        {label: "Time", key: "TIME", type: "string"},
+        {label: "ID",   key: "ID",   type: "string"},
+        {label: "Mute", key: "MUTE", type: "bool",
+         widget: "checkbox", enabled_key: "CAN_MUTE"},
+        {label: "",     key: "RESET", type: "string",
+         widget: "button", text: "Reset",
+         visible_key: "CAN_RESET"},
+    ]);

{pgwidgets_js-0.3.0 → pgwidgets_js-0.3.2}/docs/widgets/layout.rst

@@ -8,7 +8,8 @@ TopLevel
 
 The root-level container widget. Uses absolute positioning and attaches
 to the document body. Typically the outermost widget in a pgwidgets
-application.
+application.  A single-child container: ``get_children()`` returns its
+0- or 1-element child list.
 
 **Constructor:** ``new Widgets.TopLevel({title, icon, resizable,
 moveable, closeable, minimizable, maximizable, lowerable,
@@ -115,6 +116,11 @@ Vertical box layout. Children are stacked top to bottom.
      - Add a child widget. *stretch* (0 or 1) controls whether it expands.
    * - ``set_spacing(gap)``
      - Set spacing between children in pixels.
+   * - ``set_align(align)``
+     - Cross-axis alignment of children.  For a vertical box
+       this is the horizontal axis -- accepts ``"left"`` /
+       ``"center"`` / ``"right"``.  Maps to flex
+       ``align-items``.
 
 **Callbacks:** ``child-added``, ``child-removed`` (from ContainerWidget).
 
@@ -123,6 +129,7 @@ Vertical box layout. Children are stacked top to bottom.
    let vbox = new Widgets.VBox();
    vbox.set_spacing(8);
    vbox.set_padding(10);
+   vbox.set_align("center");    // centre children horizontally
    vbox.add_widget(label, 0);   // fixed size
    vbox.add_widget(editor, 1);  // stretches to fill
 
@@ -147,6 +154,11 @@ Horizontal box layout. Children are placed left to right.
      - Add a child widget. *stretch* controls whether it expands.
    * - ``set_spacing(gap)``
      - Set spacing between children in pixels.
+   * - ``set_align(align)``
+     - Cross-axis alignment of children.  For a horizontal box
+       this is the vertical axis -- accepts ``"top"`` /
+       ``"center"`` / ``"bottom"``.  Maps to flex
+       ``align-items``.
 
 **Callbacks:** ``child-added``, ``child-removed``.
 
@@ -154,6 +166,7 @@ Horizontal box layout. Children are placed left to right.
 
    let hbox = new Widgets.HBox();
    hbox.set_spacing(4);
+   hbox.set_align("center");      // centre children vertically
    hbox.add_widget(button1, 0);
    hbox.add_widget(button2, 0);
 
@@ -451,6 +464,15 @@ ScrollArea
 
 Scrollable viewport wrapping a single child widget.
 
+If the child opts to fill (via ``set_expanding`` or a ``Box`` stretch
+factor) it fills the viewport when its content is smaller than the
+viewport, and grows (and scrolls) when the content is larger.  A child
+with no expand policy keeps its natural size, top-aligned.
+
+Like the other single-child containers (:ref:`widget-frame`,
+:ref:`widget-expander`, :ref:`widget-toplevel`), ``ScrollArea`` is a
+container: ``get_children()`` returns its 0- or 1-element child list.
+
 **Constructor:** ``new Widgets.ScrollArea({hscrollbar, vscrollbar})``
 
 **Options:**
@@ -476,7 +498,8 @@ Scrollable viewport wrapping a single child widget.
 Frame
 -----
 
-Titled border container for grouping widgets.
+Titled border container for grouping widgets.  A single-child container:
+``get_children()`` returns its 0- or 1-element child list.
 
 **Constructor:** ``new Widgets.Frame({title})``
 
@@ -509,7 +532,8 @@ Titled border container for grouping widgets.
 Expander
 --------
 
-Collapsible section with a clickable header.
+Collapsible section with a clickable header.  A single-child container:
+``get_children()`` returns its 0- or 1-element child list.
 
 **Constructor:** ``new Widgets.Expander({title, collapsible, shadow})``
 

{pgwidgets_js-0.3.0 → pgwidgets_js-0.3.2}/docs/widgets/menus.rst

@@ -1,6 +1,13 @@
 Menu & Toolbar Widgets
 ======================
 
+``MenuBar``, ``Menu`` and ``ToolBar`` are container widgets: the menu
+actions, submenus and toolbar items they hold (added via ``add_name`` /
+``add_menu`` / ``add_action`` / ``add_widget``) are reported by the
+standard container API -- ``get_children()`` / ``num_children()`` /
+``remove(...)``.  Separators and spacers are not widgets and are not
+included.
+
 .. _widget-menubar:
 
 MenuBar