flexablelib 3.0.3__tar.gz → 3.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. {flexablelib-3.0.3 → flexablelib-3.2.0}/CHANGELOG.md +57 -0
  2. {flexablelib-3.0.3 → flexablelib-3.2.0}/MANIFEST.in +1 -0
  3. {flexablelib-3.0.3/flexablelib.egg-info → flexablelib-3.2.0}/PKG-INFO +131 -2
  4. {flexablelib-3.0.3 → flexablelib-3.2.0}/README.md +130 -1
  5. flexablelib-3.2.0/examples/dashboard.py +178 -0
  6. flexablelib-3.2.0/flexablelib/__init__.py +12 -0
  7. flexablelib-3.2.0/flexablelib/layout.py +1894 -0
  8. flexablelib-3.2.0/flexablelib/screen.py +247 -0
  9. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/table.py +540 -56
  10. flexablelib-3.2.0/flexablelib/widgets.py +624 -0
  11. {flexablelib-3.0.3 → flexablelib-3.2.0/flexablelib.egg-info}/PKG-INFO +131 -2
  12. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib.egg-info/SOURCES.txt +6 -0
  13. {flexablelib-3.0.3 → flexablelib-3.2.0}/package.json +1 -1
  14. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/conftest.py +14 -10
  15. flexablelib-3.2.0/tests/test_v310_layout.py +573 -0
  16. flexablelib-3.2.0/tests/test_v320_tui.py +1013 -0
  17. flexablelib-3.0.3/flexablelib/__init__.py +0 -6
  18. {flexablelib-3.0.3 → flexablelib-3.2.0}/LICENSE +0 -0
  19. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/_speedups.c +0 -0
  20. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/_width_tables.h +0 -0
  21. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/box_topology.py +0 -0
  22. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/cells.py +0 -0
  23. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/colors.py +0 -0
  24. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/columns.py +0 -0
  25. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/fast.py +0 -0
  26. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/merges.py +0 -0
  27. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/options.py +0 -0
  28. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/py.typed +0 -0
  29. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/readers.py +0 -0
  30. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/style_compositions.py +0 -0
  31. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/table_strings.py +0 -0
  32. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/text_width.py +0 -0
  33. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/utils.py +0 -0
  34. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib/writers.py +0 -0
  35. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib.egg-info/dependency_links.txt +0 -0
  36. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib.egg-info/requires.txt +0 -0
  37. {flexablelib-3.0.3 → flexablelib-3.2.0}/flexablelib.egg-info/top_level.txt +0 -0
  38. {flexablelib-3.0.3 → flexablelib-3.2.0}/pytest.ini +0 -0
  39. {flexablelib-3.0.3 → flexablelib-3.2.0}/setup.cfg +0 -0
  40. {flexablelib-3.0.3 → flexablelib-3.2.0}/setup.py +0 -0
  41. {flexablelib-3.0.3 → flexablelib-3.2.0}/style_examples.md +0 -0
  42. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/helpers.py +0 -0
  43. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_align_indicators.py +0 -0
  44. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_box_topology.py +0 -0
  45. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_cells.py +0 -0
  46. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_columns.py +0 -0
  47. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_excel.py +0 -0
  48. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_features.py +0 -0
  49. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_issues.py +0 -0
  50. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_merge_edge_matrix.py +0 -0
  51. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_merge_fill.py +0 -0
  52. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_merges.py +0 -0
  53. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_public_api_edges.py +0 -0
  54. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_readme_examples.py +0 -0
  55. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_stress_matrix.py +0 -0
  56. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_style_line_widths.py +0 -0
  57. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_styles.py +0 -0
  58. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_text_width.py +0 -0
  59. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_two_pass_measurement.py +0 -0
  60. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_upstream_issues.py +0 -0
  61. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v2021_fixes.py +0 -0
  62. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v210_rows_copy.py +0 -0
  63. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v2110_fixes.py +0 -0
  64. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v211_fixes.py +0 -0
  65. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v213_features.py +0 -0
  66. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v214_features.py +0 -0
  67. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v215_features.py +0 -0
  68. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v216_features.py +0 -0
  69. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v217_features.py +0 -0
  70. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v218_features.py +0 -0
  71. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v219_coverage.py +0 -0
  72. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v219_fixes.py +0 -0
  73. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v220_exports.py +0 -0
  74. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v221_fixes.py +0 -0
  75. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v222_fixes.py +0 -0
  76. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v223_fixes.py +0 -0
  77. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v224_fixes.py +0 -0
  78. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v230_none.py +0 -0
  79. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v231_fixes.py +0 -0
  80. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v232_merge_ansi.py +0 -0
  81. {flexablelib-3.0.3 → flexablelib-3.2.0}/tests/test_v300_style_names.py +0 -0
  82. {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/benchmark.py +0 -0
  83. {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/generate_width_tables.py +0 -0
  84. {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/readme_gallery.py +0 -0
  85. {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/stress_matrix.py +0 -0
  86. {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/style_examples.py +0 -0
  87. {flexablelib-3.0.3 → flexablelib-3.2.0}/tools/text_to_png.py +0 -0
@@ -2,6 +2,63 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
4
4
 
5
+ ## [3.2.0] - 2026-11-11
6
+
7
+ ### Added
8
+ - `Grid(column_widths=[...])`: fixed, `'auto'`, `'Nfr'`, `'N%'` and
9
+ `(size, min, max)` columns, or a dict of layouts per width (breakpoints).
10
+ Columns that cannot fit stack; `collapse_below` stacks below a width.
11
+ - `GridCell(row_span=n)`, with CSS-style sparse auto-placement, plus
12
+ `valign`, `title`, `title_align`, `color`, `stretch`, `padding` and
13
+ `hide_below` (hide a cell on narrow terminals). `Grid.add()` takes them.
14
+ - `Grid(border=...)`: one shared frame around and between the cells
15
+ (`single`, `rounded`, `double`, `heavy`, `ascii`) with correct junctions
16
+ for spans and row spans, a title per cell set into its top border,
17
+ `border_color`, `title_color` and cell `padding`.
18
+ - `Grid.render(width, height)` / `Grid(height=...)` and `row_heights`
19
+ (fixed, `auto`, fractions, bounds, per-width dicts): exact heights, spare
20
+ lines to fraction rows, overflow trimmed bottom-up with the frame kept
21
+ closed. Children that take a height (grids, `LogView`...) fill their slot.
22
+ - Widgets: `ProgressBar` (eighth-cell precision, thresholds, value formats),
23
+ `Sparkline`, `BarChart`, `StatusBar`, `KeyHints`, `LogView` (levels
24
+ coloured, tail to height), `Text` and `Rule`.
25
+ - `Screen`: header and footer pinned to the terminal's edges, the body gets
26
+ the lines in between. `Live`: redraw in place on the alternate screen, or
27
+ plain frames on a pipe; `run(step, interval, iterations)`.
28
+ - `examples/dashboard.py`: a complete terminal dashboard (three layouts by
29
+ width, themes, borders, `--live`).
30
+
31
+ ### Unchanged
32
+ - A grid without the new options renders exactly as in 3.1.0.
33
+
34
+ ## [3.1.0] - 2026-11-11
35
+
36
+ ### Added
37
+ - `Card`: one record in a frame, in any of the 54 styles and the 15
38
+ themes. The title goes into the top border (`╭─ Title ───╮`) when the
39
+ style draws one; subtitle, `label value` fields (or a grid of tiles with
40
+ `field_columns=2`/`'auto'`), any renderable as `body`, footer and
41
+ `[ action ]` chips. Colours fill the card frame to frame; panel and
42
+ shadow work as on tables.
43
+ - `Grid` and `GridCell`: lay cards, tables, text and other grids out in
44
+ columns that reflow with the width (`columns='auto'` or n, `min_width`,
45
+ spans, nesting, equal-height rows) -- a grid of cards or a whole terminal
46
+ screen.
47
+ - `Table.render(width)` / `responsive=True`: the table when it fits, then
48
+ squeezed, then without low-priority columns (`column_priority`), then as
49
+ cards (`to_cards()`) in a responsive grid. `breakpoints`,
50
+ `card_options`, `render_mode()` and `natural_width()`.
51
+ - `Table.subtitle`, `title_position='border'`, `caption_position='border'`,
52
+ `title_align`, `title_color`. A border title never covers a corner or a
53
+ column junction; it falls back to a line above.
54
+ - `flexablelib.layout.wrap_panel` / `add_shadow`, shared by tables and
55
+ cards.
56
+
57
+ ### Fixed
58
+ - Columns in `hide_columns` no longer count toward the width the fit pass
59
+ has to save, so a table that fits once they are hidden is no longer
60
+ squeezed as if they were still drawn.
61
+
5
62
  ## [3.0.3] - 2026-11-11
6
63
 
7
64
  ### Fixed
@@ -9,3 +9,4 @@ include style_examples.md
9
9
  include flexablelib/py.typed
10
10
  include pytest.ini
11
11
  recursive-include tests *.py
12
+ recursive-include examples *.py
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: flexablelib
3
- Version: 3.0.3
3
+ Version: 3.2.0
4
4
  Summary: Fast, dependency-free terminal tables for Python: 54 border styles, ANSI colors, cell merges, decimal alignment, width fitting, and CSV/Markdown/HTML/Excel/LaTeX I/O.
5
5
  Home-page: https://github.com/Opus-Perpetuus/flexablelib
6
6
  Author: Benjamin Ramirez
@@ -504,6 +504,131 @@ table.merge_cells(0, 0, 2, 2, value='Total', align='r')
504
504
  A merge never widens the table -- columns are still sized by their unmerged
505
505
  content -- so text longer than its span is truncated.
506
506
 
507
+ ## Cards, grids, responsive tables and terminal interfaces
508
+
509
+ `Card` draws one record in a frame, in any of the table styles. The title goes
510
+ into the top border when the style draws one:
511
+
512
+ ```python
513
+ from flexablelib import Card
514
+
515
+ card = Card(title='Ana', subtitle='Norte',
516
+ fields={'Edad': 28, 'Ciudad': 'Guadalajara'},
517
+ footer='actualizado hoy')
518
+ print(card.render(width=30))
519
+ ```
520
+
521
+ ```
522
+ ╭─ Ana ──────────────────────╮
523
+ │ Norte │
524
+ ├────────────────────────────┤
525
+ │ Edad 28 │
526
+ │ Ciudad Guadalajara │
527
+ ├────────────────────────────┤
528
+ │ actualizado hoy │
529
+ ╰────────────────────────────╯
530
+ ```
531
+
532
+ `field_columns=2` (or `'auto'`) lays the fields out as a grid of tiles, and
533
+ `actions` adds `[ Action ]` chips:
534
+
535
+ ```
536
+ ╭─ Pedido 42 ────────────────────╮
537
+ │ Cliente Total │
538
+ │ José $1,200 │
539
+ │ Estado Fecha │
540
+ │ Enviado 11/11 │
541
+ ├────────────────────────────────┤
542
+ │ [ Ver ] [ Editar ] │
543
+ ╰────────────────────────────────╯
544
+ ```
545
+
546
+ Cards take `style_name`, `theme` (the table themes), `border_color`,
547
+ `title_color`, `label_color`, `value_colors`, `color` (a background for the
548
+ whole card), `zebra`, `panel` and `shadow`.
549
+
550
+ `table.render(width)` makes a table responsive: the normal table when it fits,
551
+ without its low-priority columns next, squeezed and wrapped after that, and
552
+ one card per row when nothing else fits. `width` defaults to
553
+ `max_width`, then the terminal width; `responsive=True` makes `print(table)` do
554
+ the same.
555
+
556
+ ```python
557
+ table.title, table.title_position = 'Personas', 'border'
558
+ table.column_priority = {'Correo': 3} # hidden first
559
+ table.card_options = {'subtitle_field': 'Grupo', 'fields': ['Edad', 'Ciudad']}
560
+ table.render(width=80) # table
561
+ table.render(width=46) # table without "Correo"
562
+ table.render(width=30) # cards
563
+ ```
564
+
565
+ ```
566
+ ╭─────────┬────────┬──────┬─ Personas ──┬──────────────────╮
567
+ │ Nombre │ Grupo │ Edad │ Ciudad │ Correo │
568
+ ├─────────┼────────┼──────┼─────────────┼──────────────────┤
569
+ │ Ana │ Norte │ 28 │ Guadalajara │ ana@example.com │
570
+ │ Luna 🌸 │ Centro │ 22 │ Mérida │ luna@example.com │
571
+ ╰─────────┴────────┴──────┴─────────────┴──────────────────╯
572
+
573
+ Personas
574
+ ╭─ Ana ──────────────────────╮
575
+ │ Norte │
576
+ ├────────────────────────────┤
577
+ │ Edad 28 │
578
+ │ Ciudad Guadalajara │
579
+ ╰────────────────────────────╯
580
+ ```
581
+
582
+ `Grid` places cards, tables, text and other grids in columns that reflow with
583
+ the width -- a grid of cards or a whole terminal screen:
584
+
585
+ ```python
586
+ from flexablelib import Grid, GridCell
587
+
588
+ Grid(table.to_cards(), min_width=28).render(width=100) # 3 columns, 2 at 62, 1 at 40
589
+ Grid([GridCell('Ventas de noviembre', span=3),
590
+ GridCell(table, span=2), Grid(cards, columns=1)], columns=3)
591
+ ```
592
+
593
+ ### Terminal interfaces
594
+
595
+ Since 3.2.0 a grid can size its columns (`12`, `'auto'`, `'2fr'`, `'30%'`,
596
+ bounds, or one layout per width), span rows, share one border with proper
597
+ junctions and a title per cell, and fill an exact height. Widgets --
598
+ `ProgressBar`, `Sparkline`, `BarChart`, `StatusBar`, `KeyHints`, `LogView`,
599
+ `Text`, `Rule` -- drop into it, `Screen` pins a header and footer to the
600
+ terminal's edges and `Live` redraws in place:
601
+
602
+ ```python
603
+ from flexablelib import (Grid, GridCell, LogView, ProgressBar, Sparkline,
604
+ Text)
605
+
606
+ Grid([
607
+ GridCell(Text('▸ Resumen\n Ventas\n Ajustes'), row_span=2, title='Menú'),
608
+ GridCell(ProgressBar(72, label='CPU', thresholds={0.7: 'yellow'}),
609
+ title='Recursos'),
610
+ GridCell(Sparkline([3, 5, 2, 8, 6, 9, 4, 7], label='rps', show_last=True),
611
+ title='Tráfico'),
612
+ GridCell(LogView(['10:00 INFO arranque', '10:01 WARN lento']), span=2,
613
+ title='Eventos'),
614
+ ], column_widths=[14, '1fr', '1fr'], border='rounded').render(width=64)
615
+ ```
616
+
617
+ ```
618
+ ╭─ Menú ───────┬─ Recursos ────────────┬─ Tráfico ─────────────╮
619
+ │ ▸ Resumen │ CPU ████████▋░░░ 72% │ rps ▂▄▁▇▅█▃▆ 7 │
620
+ │ Ventas ├─ Eventos ─────────────┴───────────────────────┤
621
+ │ Ajustes │ 10:00 INFO arranque │
622
+ │ │ 10:01 WARN lento │
623
+ ╰──────────────┴───────────────────────────────────────────────╯
624
+ ```
625
+
626
+ A whole dashboard with a sidebar, KPI cards, a coloured table with merges,
627
+ bars, sparklines and a log: [examples/dashboard.py](https://github.com/Opus-Perpetuus/flexablelib/blob/main/examples/dashboard.py)
628
+ (`python examples/dashboard.py --live 10`).
629
+
630
+ More in [docs/LAYOUT.md](https://github.com/Opus-Perpetuus/flexablelib/blob/main/docs/LAYOUT.md).
631
+
507
632
  ## Notes
508
633
 
509
634
  - A column named ``"i"`` does not collide with the index column (`utils.IndexColumnTitle`).
@@ -517,14 +642,18 @@ Open work and the issue map: [docs/ISSUES.md](https://github.com/Opus-Perpetuus/
517
642
  ```
518
643
  flexablelib/ # GitHub repository
519
644
  ├── flexablelib/ the Python package (no runtime dependencies)
520
- │ ├── __init__.py public API: Table, TableComposition, SeparatorLine
645
+ │ ├── __init__.py public API: Table, Card, Grid, widgets, Screen, Live
521
646
  │ ├── table.py the Table class — state and render orchestration
647
+ │ ├── layout.py Card, Grid, GridCell, panel and shadow
648
+ │ ├── widgets.py ProgressBar, Sparkline, BarChart, StatusBar, LogView…
649
+ │ ├── screen.py Screen (sticky header/footer) and Live (redraw)
522
650
  │ ├── columns.py type inference, alignment, column widths
523
651
  │ ├── style_compositions.py the 54 border styles, as data
524
652
  │ ├── table_strings.py separator lines and data rows
525
653
  │ ├── cells.py cell padding, justification, wrapping
526
654
  │ ├── options.py constants and defaults
527
655
  │ └── utils.py type predicates and small helpers
656
+ ├── examples/ runnable demos (dashboard.py)
528
657
  ├── tests/ pytest suite — see ARCHITECTURE.md#testing
529
658
  ├── docs/ issue history and design notes
530
659
  ├── logos/ brand assets — see logos/README.md
@@ -439,6 +439,131 @@ table.merge_cells(0, 0, 2, 2, value='Total', align='r')
439
439
  A merge never widens the table -- columns are still sized by their unmerged
440
440
  content -- so text longer than its span is truncated.
441
441
 
442
+ ## Cards, grids, responsive tables and terminal interfaces
443
+
444
+ `Card` draws one record in a frame, in any of the table styles. The title goes
445
+ into the top border when the style draws one:
446
+
447
+ ```python
448
+ from flexablelib import Card
449
+
450
+ card = Card(title='Ana', subtitle='Norte',
451
+ fields={'Edad': 28, 'Ciudad': 'Guadalajara'},
452
+ footer='actualizado hoy')
453
+ print(card.render(width=30))
454
+ ```
455
+
456
+ ```
457
+ ╭─ Ana ──────────────────────╮
458
+ │ Norte │
459
+ ├────────────────────────────┤
460
+ │ Edad 28 │
461
+ │ Ciudad Guadalajara │
462
+ ├────────────────────────────┤
463
+ │ actualizado hoy │
464
+ ╰────────────────────────────╯
465
+ ```
466
+
467
+ `field_columns=2` (or `'auto'`) lays the fields out as a grid of tiles, and
468
+ `actions` adds `[ Action ]` chips:
469
+
470
+ ```
471
+ ╭─ Pedido 42 ────────────────────╮
472
+ │ Cliente Total │
473
+ │ José $1,200 │
474
+ │ Estado Fecha │
475
+ │ Enviado 11/11 │
476
+ ├────────────────────────────────┤
477
+ │ [ Ver ] [ Editar ] │
478
+ ╰────────────────────────────────╯
479
+ ```
480
+
481
+ Cards take `style_name`, `theme` (the table themes), `border_color`,
482
+ `title_color`, `label_color`, `value_colors`, `color` (a background for the
483
+ whole card), `zebra`, `panel` and `shadow`.
484
+
485
+ `table.render(width)` makes a table responsive: the normal table when it fits,
486
+ without its low-priority columns next, squeezed and wrapped after that, and
487
+ one card per row when nothing else fits. `width` defaults to
488
+ `max_width`, then the terminal width; `responsive=True` makes `print(table)` do
489
+ the same.
490
+
491
+ ```python
492
+ table.title, table.title_position = 'Personas', 'border'
493
+ table.column_priority = {'Correo': 3} # hidden first
494
+ table.card_options = {'subtitle_field': 'Grupo', 'fields': ['Edad', 'Ciudad']}
495
+ table.render(width=80) # table
496
+ table.render(width=46) # table without "Correo"
497
+ table.render(width=30) # cards
498
+ ```
499
+
500
+ ```
501
+ ╭─────────┬────────┬──────┬─ Personas ──┬──────────────────╮
502
+ │ Nombre │ Grupo │ Edad │ Ciudad │ Correo │
503
+ ├─────────┼────────┼──────┼─────────────┼──────────────────┤
504
+ │ Ana │ Norte │ 28 │ Guadalajara │ ana@example.com │
505
+ │ Luna 🌸 │ Centro │ 22 │ Mérida │ luna@example.com │
506
+ ╰─────────┴────────┴──────┴─────────────┴──────────────────╯
507
+
508
+ Personas
509
+ ╭─ Ana ──────────────────────╮
510
+ │ Norte │
511
+ ├────────────────────────────┤
512
+ │ Edad 28 │
513
+ │ Ciudad Guadalajara │
514
+ ╰────────────────────────────╯
515
+ ```
516
+
517
+ `Grid` places cards, tables, text and other grids in columns that reflow with
518
+ the width -- a grid of cards or a whole terminal screen:
519
+
520
+ ```python
521
+ from flexablelib import Grid, GridCell
522
+
523
+ Grid(table.to_cards(), min_width=28).render(width=100) # 3 columns, 2 at 62, 1 at 40
524
+ Grid([GridCell('Ventas de noviembre', span=3),
525
+ GridCell(table, span=2), Grid(cards, columns=1)], columns=3)
526
+ ```
527
+
528
+ ### Terminal interfaces
529
+
530
+ Since 3.2.0 a grid can size its columns (`12`, `'auto'`, `'2fr'`, `'30%'`,
531
+ bounds, or one layout per width), span rows, share one border with proper
532
+ junctions and a title per cell, and fill an exact height. Widgets --
533
+ `ProgressBar`, `Sparkline`, `BarChart`, `StatusBar`, `KeyHints`, `LogView`,
534
+ `Text`, `Rule` -- drop into it, `Screen` pins a header and footer to the
535
+ terminal's edges and `Live` redraws in place:
536
+
537
+ ```python
538
+ from flexablelib import (Grid, GridCell, LogView, ProgressBar, Sparkline,
539
+ Text)
540
+
541
+ Grid([
542
+ GridCell(Text('▸ Resumen\n Ventas\n Ajustes'), row_span=2, title='Menú'),
543
+ GridCell(ProgressBar(72, label='CPU', thresholds={0.7: 'yellow'}),
544
+ title='Recursos'),
545
+ GridCell(Sparkline([3, 5, 2, 8, 6, 9, 4, 7], label='rps', show_last=True),
546
+ title='Tráfico'),
547
+ GridCell(LogView(['10:00 INFO arranque', '10:01 WARN lento']), span=2,
548
+ title='Eventos'),
549
+ ], column_widths=[14, '1fr', '1fr'], border='rounded').render(width=64)
550
+ ```
551
+
552
+ ```
553
+ ╭─ Menú ───────┬─ Recursos ────────────┬─ Tráfico ─────────────╮
554
+ │ ▸ Resumen │ CPU ████████▋░░░ 72% │ rps ▂▄▁▇▅█▃▆ 7 │
555
+ │ Ventas ├─ Eventos ─────────────┴───────────────────────┤
556
+ │ Ajustes │ 10:00 INFO arranque │
557
+ │ │ 10:01 WARN lento │
558
+ ╰──────────────┴───────────────────────────────────────────────╯
559
+ ```
560
+
561
+ A whole dashboard with a sidebar, KPI cards, a coloured table with merges,
562
+ bars, sparklines and a log: [examples/dashboard.py](https://github.com/Opus-Perpetuus/flexablelib/blob/main/examples/dashboard.py)
563
+ (`python examples/dashboard.py --live 10`).
564
+
565
+ More in [docs/LAYOUT.md](https://github.com/Opus-Perpetuus/flexablelib/blob/main/docs/LAYOUT.md).
566
+
442
567
  ## Notes
443
568
 
444
569
  - A column named ``"i"`` does not collide with the index column (`utils.IndexColumnTitle`).
@@ -452,14 +577,18 @@ Open work and the issue map: [docs/ISSUES.md](https://github.com/Opus-Perpetuus/
452
577
  ```
453
578
  flexablelib/ # GitHub repository
454
579
  ├── flexablelib/ the Python package (no runtime dependencies)
455
- │ ├── __init__.py public API: Table, TableComposition, SeparatorLine
580
+ │ ├── __init__.py public API: Table, Card, Grid, widgets, Screen, Live
456
581
  │ ├── table.py the Table class — state and render orchestration
582
+ │ ├── layout.py Card, Grid, GridCell, panel and shadow
583
+ │ ├── widgets.py ProgressBar, Sparkline, BarChart, StatusBar, LogView…
584
+ │ ├── screen.py Screen (sticky header/footer) and Live (redraw)
457
585
  │ ├── columns.py type inference, alignment, column widths
458
586
  │ ├── style_compositions.py the 54 border styles, as data
459
587
  │ ├── table_strings.py separator lines and data rows
460
588
  │ ├── cells.py cell padding, justification, wrapping
461
589
  │ ├── options.py constants and defaults
462
590
  │ └── utils.py type predicates and small helpers
591
+ ├── examples/ runnable demos (dashboard.py)
463
592
  ├── tests/ pytest suite — see ARCHITECTURE.md#testing
464
593
  ├── docs/ issue history and design notes
465
594
  ├── logos/ brand assets — see logos/README.md
@@ -0,0 +1,178 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ A complete terminal dashboard built only with flexablelib.
4
+
5
+ python examples/dashboard.py # one frame, terminal size
6
+ python examples/dashboard.py --width 120 --height 40 --theme neon
7
+ python examples/dashboard.py --live 10 # redraw 10 times, 1 s apart
8
+ python examples/dashboard.py --no-color --border ascii
9
+
10
+ Pieces: Screen (sticky header and footer), a bordered Grid with column
11
+ widths, a row-spanning sidebar and cell titles, KPI cards, a coloured table
12
+ with merged cells, progress bars, sparklines, a bar chart and a log.
13
+ """
14
+
15
+ import argparse
16
+ import math
17
+ import os
18
+ import sys
19
+
20
+ sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
21
+ '..'))
22
+
23
+ from flexablelib import (BarChart, Card, Grid, GridCell, KeyHints, # noqa
24
+ Live, LogView, ProgressBar, Screen, Sparkline,
25
+ StatusBar, Table, Text)
26
+
27
+ THEME_ACCENTS = {
28
+ 'ocean': ('#7dc3ff', 'black on #7dc3ff', '#5f87af'),
29
+ 'neon': ('#ff5fd7', 'black on #ff5fd7', '#af5fff'),
30
+ 'forest': ('#87d787', 'black on #87d787', '#5f875f'),
31
+ 'ember': ('#ffaf5f', 'black on #ffaf5f', '#af5f00'),
32
+ 'midnight': ('#8787ff', 'white on #303070', '#5f5f87'),
33
+ 'dark': ('#d0d0d0', 'black on #d0d0d0', '#6c6c6c'),
34
+ 'mono': (None, 'reverse', None),
35
+ }
36
+
37
+
38
+ def wave(tick, n, base, amp, phase=0.0):
39
+ return [round(base + amp * math.sin((i + tick) / 2.3 + phase) +
40
+ amp * 0.4 * math.sin((i + tick) * 1.7 + phase), 1)
41
+ for i in range(n)]
42
+
43
+
44
+ def sales_table(theme, colors):
45
+ t = Table(headers=['Región', 'Tienda', 'Ventas', 'Δ %', 'Estado'])
46
+ rows = [
47
+ ['Norte', 'Monterrey', 18250.5, 12.4, 'OK'],
48
+ ['Norte', 'Saltillo', 9120.0, -3.1, 'Revisar'],
49
+ ['Centro', 'CDMX', 25400.75, 8.9, 'OK'],
50
+ ['Centro', 'Puebla', 7310.2, 1.2, 'OK'],
51
+ ['Sur', 'Mérida', 6890.0, -7.5, 'Alerta'],
52
+ ['Sur', 'Oaxaca', 4210.4, 2.0, 'OK'],
53
+ ]
54
+ for row in rows:
55
+ t.add_row(row)
56
+ t.apply_theme(theme)
57
+ t.style_name = 'single'
58
+ t.use_colors = colors
59
+ t.float_format = ',.1f'
60
+ t.expand_to_window = True
61
+ t.merge_cells(0, 0, last_row=1)
62
+ t.merge_cells(2, 0, last_row=3)
63
+ t.merge_cells(4, 0, last_row=5)
64
+ t.color_rule = lambda value, row, column: (
65
+ ('red' if value < 0 else 'green') if column == 'Δ %' else
66
+ {'OK': 'green', 'Revisar': 'yellow', 'Alerta': 'bold red'}.get(value)
67
+ if column == 'Estado' else None)
68
+ t.column_priority = {'Estado': 2, 'Tienda': 3}
69
+ t.card_options = {'min_width': 24, 'fields': ['Ventas', 'Δ %']}
70
+ return t
71
+
72
+
73
+ def build(theme='ocean', border='rounded', colors=True, tick=0):
74
+ accent, bar_color, border_color = THEME_ACCENTS.get(
75
+ theme, THEME_ACCENTS['ocean'])
76
+ cpu = wave(tick, 40, 55, 25)
77
+ mem = wave(tick, 40, 62, 8, 1.0)
78
+ net = wave(tick, 40, 40, 30, 2.0)
79
+
80
+ kpis = [
81
+ Card(title='Ventas hoy', fields={'MXN': '$71,182', 'vs ayer': '+6.2%'},
82
+ field_columns=2, theme=theme, use_colors=colors,
83
+ value_colors={'vs ayer': 'green'}),
84
+ Card(title='Pedidos', fields={'Total': 1284, 'Abiertos': 37},
85
+ field_columns=2, theme=theme, use_colors=colors),
86
+ Card(title='Clientes', fields={'Activos': 942, 'Nuevos': 58},
87
+ field_columns=2, theme=theme, use_colors=colors),
88
+ Card(title='Ticket', fields={'Prom.': '$554', 'Máx.': '$9,870'},
89
+ field_columns=2, theme=theme, use_colors=colors),
90
+ ]
91
+ menu_items = ['Resumen', 'Ventas', 'Inventario', 'Clientes', 'Envíos',
92
+ 'Reportes', 'Ajustes']
93
+ menu = '\n'.join(
94
+ ('\x1b[1m▸ {0}\x1b[0m'.format(item) if i == 0 else ' ' + item)
95
+ for i, item in enumerate(menu_items))
96
+ resources = Grid([
97
+ ProgressBar(cpu[-1], label='CPU', label_width=5, value_width=10,
98
+ thresholds={0.7: 'yellow', 0.9: 'red'}, use_colors=colors),
99
+ ProgressBar(mem[-1], label='RAM', label_width=5, value_width=10,
100
+ thresholds={0.7: 'yellow', 0.9: 'red'}, use_colors=colors),
101
+ ProgressBar(412, 512, label='Disco', label_width=5, value_width=10,
102
+ value_format='{value:.0f}/{total:.0f} GB',
103
+ thresholds={0.7: 'yellow', 0.9: 'red'}, use_colors=colors),
104
+ Sparkline(cpu, label='CPU', label_width=5, show_last=True, color=accent,
105
+ use_colors=colors),
106
+ Sparkline(net, label='Red', label_width=5, show_last=True, color='magenta',
107
+ use_colors=colors),
108
+ ], columns=1, row_gap=0)
109
+ chart = BarChart({'Laptops': 412, 'Monitores': 268, 'Teclados': 190,
110
+ 'Audífonos': 151, 'Cables': 87}, sort=True,
111
+ color=accent, use_colors=colors)
112
+ log = LogView([
113
+ '09:58:02 INFO sincronización de inventario completa',
114
+ '09:58:40 OK pedido #1281 enviado (Mérida)',
115
+ '09:59:13 WARN latencia de pagos 820 ms',
116
+ '09:59:57 INFO 12 usuarios conectados',
117
+ '10:00:21 ERROR timeout en la API de envíos (reintento 1/3)',
118
+ '10:00:24 OK API de envíos recuperada',
119
+ '10:01:{0:02d} INFO tick {1}'.format(tick % 60, tick),
120
+ ], use_colors=colors)
121
+
122
+ body = Grid([
123
+ GridCell(Text(menu, use_colors=colors), row_span=3, title='Menú',
124
+ hide_below=110),
125
+ GridCell(Grid(kpis, min_width=22, row_gap=0, gap=1), span=2,
126
+ title='Indicadores'),
127
+ GridCell(sales_table(theme, colors), title='Ventas por región'),
128
+ GridCell(resources, title='Recursos', valign='middle'),
129
+ GridCell(chart, title='Top productos'),
130
+ GridCell(log, title='Eventos', stretch=True),
131
+ ], # Three layouts: one column, two columns, sidebar + two columns.
132
+ column_widths={0: ['1fr'], 76: ['3fr', '2fr'],
133
+ 110: [(16, 14, 18), '3fr', '2fr']},
134
+ row_heights={0: [], 76: ['auto', 'auto', '1fr']},
135
+ border=border, border_color=border_color,
136
+ title_color='bold ' + (accent or ''), use_colors=colors)
137
+ header = StatusBar('◆ flexablelib · Panel de ventas',
138
+ 'Resumen', 'tick {0} · 11/11/2026 10:01'.format(tick),
139
+ color=bar_color, use_colors=colors)
140
+ footer = KeyHints({'q': 'Salir', '↑↓': 'Mover', 'Enter': 'Abrir',
141
+ '/': 'Buscar', 'F5': 'Refrescar', '?': 'Ayuda'},
142
+ key_color=bar_color, use_colors=colors)
143
+ return Screen(body=body, header=header, footer=footer)
144
+
145
+
146
+ def main(argv=None):
147
+ parser = argparse.ArgumentParser(description=__doc__.split('\n\n')[1])
148
+ parser.add_argument('--width', type=int)
149
+ parser.add_argument('--height', type=int)
150
+ parser.add_argument('--theme', default='ocean',
151
+ choices=sorted(THEME_ACCENTS))
152
+ parser.add_argument('--border', default='rounded',
153
+ choices=['single', 'rounded', 'double', 'heavy',
154
+ 'ascii'])
155
+ parser.add_argument('--no-color', action='store_true')
156
+ parser.add_argument('--live', type=int, metavar='N',
157
+ help='redraw N frames, one per --interval seconds')
158
+ parser.add_argument('--interval', type=float, default=1.0)
159
+ args = parser.parse_args(argv)
160
+ colors = not args.no_color and (args.live is not None or None)
161
+ if colors is None:
162
+ from flexablelib.colors import supports_color
163
+ colors = supports_color()
164
+ if args.live:
165
+ live = Live(build(args.theme, args.border, colors), width=args.width,
166
+ height=args.height)
167
+
168
+ def step(i):
169
+ live.renderable = build(args.theme, args.border, colors, i)
170
+ live.run(step, interval=args.interval, iterations=args.live)
171
+ return 0
172
+ screen = build(args.theme, args.border, colors)
173
+ print(screen.render(width=args.width, height=args.height))
174
+ return 0
175
+
176
+
177
+ if __name__ == '__main__':
178
+ sys.exit(main())
@@ -0,0 +1,12 @@
1
+ from .table import Table
2
+ from .style_compositions import TableComposition, SeparatorLine
3
+ from .layout import Card, Grid, GridCell
4
+ from .widgets import (ProgressBar, Sparkline, BarChart, StatusBar, KeyHints,
5
+ LogView, Text, Rule)
6
+ from .screen import Screen, Live
7
+
8
+ # Names, not the objects themselves: `from flexablelib import *` walks this
9
+ # list and raises TypeError on anything that is not a string.
10
+ __all__ = ['Table', 'TableComposition', 'SeparatorLine', 'Card', 'Grid',
11
+ 'GridCell', 'ProgressBar', 'Sparkline', 'BarChart', 'StatusBar',
12
+ 'KeyHints', 'LogView', 'Text', 'Rule', 'Screen', 'Live']