rukbat 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbd7509f4fe7e264acc4fe9dc0f51fedfc0c953a15f115046c4dd54557540263
-  data.tar.gz: 750029435921d213b829a14a87ece225e926c9d0aa4d876138071f01405b09ef
+  metadata.gz: 3a2a475aecf838cbaf8d29c8f72a546dfb56bf3db1fe006693ce4f7dd6a9edc3
+  data.tar.gz: 85e3dd7726823898c5f92072752c97ada40deb073d7f4c557a1f0792c6bf4327
 SHA512:
-  metadata.gz: 6659e6022995046877f65163bea1ecd7412181591b69376d0b369013832c2507e75576c038914a33b86a3871fabdf86390bd32840eca70c647daa9b955b3f085
-  data.tar.gz: 489ff8a98679c21b4d7f70481ad161cae366e94e7b0b9acec22d82a02f8c45b4d6df37229e6860faebe5fefd681544c9c532e5e315ae7f4052d72c9641b35b04
+  metadata.gz: 7c3b8efedcdcc9792c74fbcd3df9d038534b2dddaff73df32feb1e322261a4d2550d642e0ef6989d2c2de714ba8e2fb9dc219ae3f5ad55cf803382575c5b8305
+  data.tar.gz: 89ebb5d63ac35ae5bae9425103bf78a2f3f09039fd152c734d5d5e12b0cae0bd2f40469d88d8deebdf460104ca2261c0634ca8974ff5d9e4042ea19b64a07a7d

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0 — 2026-09-24
+
+- Export spreadsheet pages through Zaniah vector recording and Okab PDF drawing while preserving pagination, formatting, and searchable text.
+
+## 0.3.0 — 2026-09-24
+
+- Add range-based whole-number input validation with undo support.
+- Add static pivot tables with sum and count aggregation.
+
 ## 0.2.0 — 2026-09-24
 
 - Add donut, scatter, area, stacked-area, and stacked-bar chart options.

data/README.md

@@ -1,29 +1,76 @@
-# Rukbat
+<h1 align="center">Rukbat</h1>
 
-Rukbat (α Sagittarii), from Arabic *rukbat al-rāmī* (“the archer’s knee”), is
-a spreadsheet application built on a sparse, persistent Denebola sheet and the
-Furud formula engine.
+<p align="center">
+  <strong>Ruby spreadsheet editor with sparse sheets, live formulas, and CSV/TSV workflows</strong>
+</p>
 
-The current implementation includes a virtualized million-row grid, formula
-editing and completion, multi-sheet formulas, range summaries, undo/redo,
-structural row/column edits, formatting, sorting, filtering, duplicate removal,
-find/replace, comments, named ranges, conditional formatting, line/bar/pie,
-donut/scatter/area/stacked charts, CSV/TSV import/export, and searchable PDF
-export. On arm64 macOS
-with Ruby 4.0.6, the million-row integrated scroll benchmark measured 11.383 ms
-against a 16.67 ms budget, and the 100,000-cell edit/recalculation benchmark
-measured 1.773 s against a 3 s budget. Formula compatibility, public CI, and
-dependency releases remain before the first release.
+<p align="center">
+  <a href="https://rubygems.org/gems/rukbat"><img src="https://img.shields.io/gem/v/rukbat.svg" alt="Gem version"></a>
+  <a href="https://rubygems.org/gems/rukbat"><img src="https://img.shields.io/gem/dt/rukbat.svg" alt="Gem downloads"></a>
+  <a href="https://github.com/noxdea/rukbat/actions/workflows/main.yml"><img src="https://github.com/noxdea/rukbat/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/Ruby-%3E%3D%203.2-cc342d.svg" alt="Ruby 3.2 or newer">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
 
-## Install
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#workbook-api">Workbook API</a> ·
+  <a href="#development">Development</a>
+</p>
 
-```ruby
-gem "rukbat"
+---
+
+Rukbat combines [Denebola](https://github.com/noxdea/denebola)'s persistent,
+sparse sheets with [Furud](https://github.com/noxdea/furud)'s formula engine.
+It opens CSV and TSV files in a graphical editor or an interactive terminal,
+and also exposes workbooks as a Ruby API.
+Its name comes from Rukbat (α Sagittarii), Arabic *rukbat al-rāmī*
+(“the archer’s knee”).
+
+## Features
+
+- A virtualized million-row grid with formula editing, completion, multi-sheet references, and range summaries
+- Undo/redo, row and column edits, formatting, sorting, filtering, duplicate removal, find/replace, comments, and named ranges
+- Whole-number input validation, conditional formatting, freeze panes, and static pivot tables
+- Line, bar, pie, donut, scatter, area, and stacked charts in the editor
+- CSV/TSV import and export, plus searchable PDF export with an embedded font
+
+## Installation
+
+Rukbat requires Ruby 3.2 or newer. Install the published gem:
+
+```sh
+gem install rukbat
+rukbat --version
+```
+
+Or add `gem "rukbat"` to your Gemfile. The editor needs a supported desktop
+display or an interactive terminal; the workbook API can be used without one.
+
+## Quick start
+
+Open a CSV file, start a new one, or select tab-delimited input and output:
+
+```sh
+rukbat sales.csv
+rukbat new.csv
+rukbat --tsv data.tsv
 ```
 
-Rukbat requires Ruby 3.2 or newer.
+Use the mouse to select cells, arrow keys to move, and Enter or a double-click
+to edit. The formula bar's **Apply** button commits its value. Save with
+Ctrl-S (Cmd-S on macOS); Ctrl-Z/Cmd-Z undoes, and the shifted shortcut redoes.
+The status bar shows the selected range's count, numeric count, sum, and average.
 
-## Workbooks
+The toolbar provides formats, sorting, filtering, duplicate removal,
+search/replace, comments, named ranges, conditional highlighting, freeze
+panes, print areas, and charts.
+
+## Workbook API
+
+Coordinates and formula references are one-based:
 
 ```ruby
 require "rukbat"
@@ -40,12 +87,28 @@ book.undo
 book.redo
 ```
 
-Workbook coordinates and Furud references are one-based. Denebola storage is
-zero-based internally. Sheets are immutable persistent snapshots, so undo and
-redo retain prior roots instead of copying all cells. The formula engine is
-storage-agnostic; Rukbat adapts sparse range iteration through `CellSource`.
+Denebola stores zero-based, immutable sheet snapshots internally. Undo and
+redo retain prior roots instead of copying every cell; Rukbat feeds sparse
+ranges to Furud through `CellSource`.
+
+### Validation and pivots
+
+Select a range in the editor, enter inclusive bounds, and choose **Apply
+whole-number rule**. Nonblank edits, including calculated formula results,
+must then be whole numbers within the bounds. Invalid edits are rejected
+atomically; existing values are not changed when a rule is added. **Clear
+rule** removes validation from the selected range. Rules follow structural
+edits and undo/redo, but reset when a CSV/TSV workbook is reopened.
 
-## CSV and TSV
+To create a pivot, select a rectangle including its header row, enter the
+one-based key and value column positions within that selection, choose **Sum**
+or **Count**, then **Create pivot**. The result is a static `Pivot` sheet (or
+the next unused `Pivot2`, etc.), not a live link. Formula results are used;
+groups retain first-seen order and match exact key values. Sum accepts finite
+real numbers, while Count counts nonblank values. One Undo removes the
+generated sheet.
+
+## Files and export
 
 ```ruby
 book = Rukbat::CSVFile.read("sales.csv", hint: "Windows-31J")
@@ -53,38 +116,34 @@ Rukbat::CSVFile.write(book, "sales-export.csv")
 Rukbat::CSVFile.read("data.tsv", delimiter: :tsv)
 ```
 
-Import detects and strictly decodes text with Menkar, then infers integer and
-decimal literals while leaving other fields as strings. Export writes UTF-8
-with CRLF row separators; formula cells export their calculated values by
-default. Pass `values: :input` to export stored formulas/inputs instead.
-The application refuses to replace an existing file unless it is the exact
-file read into the workbook and has not changed since loading.
-
-Run `bundle exec rukbat sales.csv` to open the graphical editor. A missing CSV
-path starts a new workbook; `--tsv` selects tab-delimited input and output.
-Use the mouse to select ranges, arrow keys to move, Enter or a double-click to
-edit, and Apply to commit the formula bar value. `Ctrl-S`/`Cmd-S` saves;
-`Ctrl-Z`/`Cmd-Z` undo and the shifted shortcut redoes. The selected range's
-count, numeric count, sum, and average appear in the status bar.
-
-The toolbar provides common number, font, alignment, fill, and border formats;
-sorting, filtering, duplicate removal, search/replace, comments, named ranges,
-positive-value highlighting, freeze/unfreeze panes, print areas, and line, bar,
-pie, donut, scatter, area, stacked-area, and stacked-bar charts.
-Freeze panes are kept per sheet and restored by undo/redo; the selected cell and
-the row/column headers before it stay visible while scrolling. **Unfreeze** removes
-all frozen rows and columns. Clear highlights removes conditional formatting
-from the active sheet.
-Select a range and choose **Set print area** to constrain PDF export; **Clear
-print area** restores full-sheet output. **Export PDF** prompts for an embeddable
-font and output path, applying the current print area. The CLI can also export
-with `bundle exec rukbat --export-pdf report.pdf --font /path/to/font.ttf`.
-Print areas are session metadata; CSV has no place to store them, so they reset
-when the workbook is reopened.
-PDF export embeds the supplied font, resolves formatted font families from the
-system font database, and applies bold/italic along with cell formatting; bold
-and italic are synthesized in the PDF when the selected face has no matching
-variant. Charts are not yet rendered.
+Import uses [Menkar](https://github.com/noxdea/menkar) to detect and decode
+text, infers integer and decimal literals, and leaves other fields as strings.
+Export writes UTF-8 with CRLF row separators and uses calculated formula
+values by default; pass `values: :input` to export stored formulas. Saving an
+opened file rejects external changes made since it was loaded.
+
+CSV/TSV saves only the active sheet. Pivot creation leaves the source sheet
+active, so activate the pivot sheet before exporting its summary. Formatting,
+validation rules, print areas, and other workbook metadata are not stored in
+CSV/TSV.
+
+Set a print area in the editor to limit PDF output, then choose **Export PDF**
+and supply an embeddable font. The command line can export directly:
+
+```sh
+rukbat --export-pdf report.pdf --font /path/to/font.ttf sales.csv
+```
+
+PDF export draws formatted cells from Zaniah's vector recording and keeps text
+searchable in Okab's PDF output. Charts are not rendered
+in PDFs. Print areas reset when the workbook is reopened.
+
+## Limits
+
+- Workbooks support 1,048,576 rows and 16,384 columns; the grid renders visible cells rather than all rows at once.
+- A workbook supports up to 256 validation ranges. A pivot handles up to 100,000 data rows and 10,000 groups.
+- CSV/TSV export is limited to 10 million cells; PDF export is limited to 100,000 cells.
+- Rukbat does not open or save XLSX/ODS files. CSV/TSV does not preserve multiple sheets or workbook metadata.
 
 ## Development
 
@@ -96,6 +155,6 @@ bundle exec rbs -I sig -I "$(bundle info --path furud)/sig" -I "$(bundle info --
 gem build --strict rukbat.gemspec
 ```
 
-The implementation is not yet a `0.1.0` release. Local performance gates pass;
-check the workplan's M17 acceptance gate for remaining compatibility, public
-CI, and dependency-release checks.
+## License
+
+Rukbat is released under the [MIT License](LICENSE.txt).

data/lib/rukbat/grid_view.rb

@@ -6,7 +6,7 @@ module Rukbat
     MAX_FILL_CELLS = 100_000
 
     attr_reader :grid, :formula_field, :active_cell, :status, :completion_session,
-      :completion_candidate
+      :completion_candidate, :validation_min_field, :validation_max_field
 
     def initialize(workbook, on_save: nil)
       super()
@@ -61,6 +61,19 @@ module Rukbat
       @set_print_area_button = UI::Button.new("Set print area", size: :sm, variant: :ghost).on_click { set_print_area }
       @clear_print_area_button = UI::Button.new("Clear print area", size: :sm, variant: :ghost).on_click { clear_print_area }
       @export_pdf_button = UI::Button.new("Export PDF", size: :sm, variant: :ghost).on_click { export_pdf }
+      @validation_min_field = UI::TextField.new("")
+      @validation_max_field = UI::TextField.new("")
+      @set_validation_button = UI::Button.new("Apply whole-number rule", size: :sm, variant: :ghost)
+        .on_click { apply_whole_number_validation }
+      @clear_validation_button = UI::Button.new("Clear rule", size: :sm, variant: :ghost)
+        .on_click { clear_input_validation }
+      @pivot_key_field = UI::TextField.new("1")
+      @pivot_value_field = UI::TextField.new("2")
+      @pivot_aggregate = :sum
+      @pivot_aggregate_dropdown = UI::Dropdown.new("Sum", items: %w[Sum Count])
+        .on_change { |value, *_| @pivot_aggregate = value.to_s.downcase.to_sym }
+      @create_pivot_button = UI::Button.new("Create pivot", size: :sm, variant: :secondary)
+        .on_click { create_pivot_table }
       @find_field = UI::TextField.new("")
       @replace_field = UI::TextField.new("")
       @find_button = UI::Button.new("Find", size: :sm, variant: :ghost).on_click { find_selection }
@@ -129,6 +142,16 @@ module Rukbat
         .child(@insert_row_button).child(@delete_rows_button)
         .child(@insert_column_button).child(@delete_columns_button)
         .child(@set_print_area_button).child(@clear_print_area_button).child(@export_pdf_button)
+      validation_toolbar = Zaniah::Div.new.flex_row.items_center.gap(cx.theme.spacing[1])
+        .child(UI::Label.new("Whole numbers", size: :sm))
+        .child(UI::Label.new("Min", size: :sm)).child(@validation_min_field.style(width: 72))
+        .child(UI::Label.new("Max", size: :sm)).child(@validation_max_field.style(width: 72))
+        .child(@set_validation_button).child(@clear_validation_button)
+      pivot_toolbar = Zaniah::Div.new.flex_row.items_center.gap(cx.theme.spacing[1])
+        .child(UI::Label.new("Pivot (selected range; first row is headers)", size: :sm))
+        .child(UI::Label.new("Key col", size: :sm)).child(@pivot_key_field.style(width: 56))
+        .child(UI::Label.new("Value col", size: :sm)).child(@pivot_value_field.style(width: 56))
+        .child(@pivot_aggregate_dropdown).child(@create_pivot_button)
       annotation_toolbar = Zaniah::Div.new.flex_row.items_center.gap(cx.theme.spacing[1])
         .child(@highlight_button).child(@comment_field.style(width: 150)).child(@comment_button)
         .child(@name_field.style(width: 120)).child(@name_button)
@@ -158,7 +181,7 @@ module Rukbat
       content = Zaniah::Div.new.flex_col.gap(cx.theme.spacing[1]).p(cx.theme.spacing[2])
         .style(width: percent(100), height: percent(100))
         .child(toolbar).child(format_toolbar).child(data_toolbar).child(structure_toolbar).child(annotation_toolbar)
-        .child(find_toolbar).child(formula_row).child(@grid.flex_1)
+        .child(validation_toolbar).child(pivot_toolbar).child(find_toolbar).child(formula_row).child(@grid.flex_1)
       content.child(@chart_component) if @chart_component
       content.child(status_row)
       content
@@ -223,6 +246,53 @@ module Rukbat
 
     private
 
+    def apply_whole_number_validation
+      top, left, bottom, right = selected_coordinates
+      minimum = Integer(@validation_min_field.value, 10)
+      maximum = Integer(@validation_max_field.value, 10)
+      @workbook.set_whole_number_validation(top, left, bottom, right,
+        minimum: minimum, maximum: maximum)
+      @status = "Whole-number rule applied to #{cell_address(top, left)}:#{cell_address(bottom, right)}"
+      request_frame
+      true
+    rescue Rukbat::Error, ArgumentError, TypeError => error
+      @status = error.message
+      request_frame
+      false
+    end
+
+    def clear_input_validation
+      top, left, bottom, right = selected_coordinates
+      @workbook.clear_input_validation(top, left, bottom, right)
+      @status = "Input rule cleared from #{cell_address(top, left)}:#{cell_address(bottom, right)}"
+      request_frame
+      true
+    rescue Rukbat::Error, ArgumentError, TypeError => error
+      @status = error.message
+      request_frame
+      false
+    end
+
+    def create_pivot_table
+      top, left, bottom, right = selected_coordinates
+      source_cell = @active_cell
+      pivot = @workbook.pivot_table(top, left, bottom, right,
+        row_key_column: Integer(@pivot_key_field.value, 10),
+        value_column: Integer(@pivot_value_field.value, 10), aggregate: @pivot_aggregate)
+      name = @workbook.add_pivot_sheet(next_pivot_sheet_name, pivot)
+      sync_grid_visibility
+      sync_frozen_panes
+      @active_cell = source_cell
+      sync_formula_field
+      @status = "Created #{name}: #{pivot.rows.length} groups (#{pivot.aggregate}); select its sheet tab to view"
+      request_frame
+      true
+    rescue Rukbat::Error, ArgumentError, TypeError => error
+      @status = error.message
+      request_frame
+      false
+    end
+
     def sort_selection
       clear_filter
       top, left, bottom, right = selected_coordinates
@@ -842,6 +912,14 @@ module Rukbat
       request_frame
     end
 
+    def next_pivot_sheet_name
+      return "Pivot" unless @workbook.sheet_names.include?("Pivot")
+
+      index = 2
+      index += 1 while @workbook.sheet_names.include?("Pivot#{index}")
+      "Pivot#{index}"
+    end
+
     def save
       @status = @on_save ? @on_save.call.to_s : "Save is unavailable"
       request_frame

data/lib/rukbat/pdf_file.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "tempfile"
+require "zaniah/vector"
+require "okab/zaniah_vector"
 
 module Rukbat
   module PDFFile
@@ -25,14 +27,17 @@ module Rukbat
       columns = area ? area.right - area.left + 1 : [current.column_count, 1].max
       raise Error, "PDF export exceeds #{MAX_CELLS} cells" if rows * columns > MAX_CELLS
 
+      renderer = Zaniah::TextSystem::Renderer.new(font: font.face)
       document = Okab::Document.new(title: "#{sheet} — Rukbat", author: "Yudai Takada", creator: "Rukbat")
       (0...rows).step(ROWS_PER_PAGE) do |row_offset|
         (0...columns).step(COLUMNS_PER_PAGE) do |column_offset|
-          render_page(document, workbook, font, font_db, font_cache, sheet, origin_row, origin_column, row_offset, column_offset,
+          render_page(document, workbook, font, renderer, font_db, font_cache, sheet, origin_row, origin_column, row_offset, column_offset,
             [rows - row_offset, ROWS_PER_PAGE].min, [columns - column_offset, COLUMNS_PER_PAGE].min)
         end
       end
       document.render
+    ensure
+      renderer&.close
     end
 
     def write(workbook, path, font:, sheet: workbook.active_sheet, font_db: nil)
@@ -55,22 +60,35 @@ module Rukbat
       raise Error, "cannot write PDF: #{error.message}"
     end
 
-    def render_page(document, workbook, font, font_db, font_cache, sheet, origin_row, origin_column, row_offset, column_offset, row_count, column_count)
-      document.page(width: PAGE_WIDTH, height: PAGE_HEIGHT) do |page|
-        first_row = origin_row + row_offset + 1
-        last_row = first_row + row_count - 1
-        page.text("#{sheet} — rows #{first_row}-#{last_row}",
-          x: MARGIN, y: PAGE_HEIGHT - MARGIN, font: font, size: 10)
-        data_top = PAGE_HEIGHT - MARGIN - 24
-        (0..row_count).each do |row_index|
-          (0..column_count).each do |column_index|
-            x = MARGIN + (column_index.zero? ? 0 : 38 + (column_index - 1) * CELL_WIDTH)
-            width = column_index.zero? ? 38 : CELL_WIDTH
-            y = data_top - row_index * CELL_HEIGHT
-            text, style = cell_text(workbook, sheet, origin_row, origin_column,
-              row_offset, column_offset, row_index, column_index)
-            paint_cell(page, text, style, font_for_style(style, font, font_db, font_cache), x, y, width)
+    def render_page(document, workbook, font, renderer, font_db, font_cache, sheet, origin_row, origin_column,
+      row_offset, column_offset, row_count, column_count)
+      styled_text = []
+      vector = Zaniah::Vector.record(width: PAGE_WIDTH, height: PAGE_HEIGHT, text_system: renderer) do
+        Zaniah::Canvas.new do |_bounds, cx|
+          scene = cx.scene
+          first_row = origin_row + row_offset + 1
+          last_row = first_row + row_count - 1
+          header = "#{sheet} — rows #{first_row}-#{last_row}"
+          renderer.paint_line(scene, renderer.layout_line(header, font: font.face, size: 10),
+            x: MARGIN, y: MARGIN, color: "#000000")
+          data_top = PAGE_HEIGHT - MARGIN - 24
+          (0..row_count).each do |row_index|
+            (0..column_count).each do |column_index|
+              x = MARGIN + (column_index.zero? ? 0 : 38 + (column_index - 1) * CELL_WIDTH)
+              width = column_index.zero? ? 38 : CELL_WIDTH
+              y = data_top - row_index * CELL_HEIGHT
+              text, style = cell_text(workbook, sheet, origin_row, origin_column,
+                row_offset, column_offset, row_index, column_index)
+              paint_cell(scene, styled_text, renderer, text, style,
+                font_for_style(style, font, font_db, font_cache), x, y, width)
+            end
           end
+        end.w(PAGE_WIDTH).h(PAGE_HEIGHT)
+      end
+      document.page(width: PAGE_WIDTH, height: PAGE_HEIGHT) do |page|
+        Okab::ZaniahVector.draw(page, vector)
+        styled_text.each do |text, x, y, font, size, color, bold, italic|
+          page.text(text, x: x, y: y, font: font, size: size, color: color, bold: bold, italic: italic)
         end
       end
     end
@@ -87,13 +105,11 @@ module Rukbat
     end
     private_class_method :cell_text
 
-    def paint_cell(page, text, style, font, x, top, width)
+    def paint_cell(scene, styled_text, renderer, text, style, font, x, top, width)
       y = top - CELL_HEIGHT
-      if style[:background]
-        page.rect(x, y, width, CELL_HEIGHT).fill(rgb(style[:background]))
-      end
-      page.rect(x, y, width, CELL_HEIGHT).stroke(rgb(style[:border_color] || "#B8BEC8"),
-        width: style[:border_width] || 0.5)
+      scene.quad(x, PAGE_HEIGHT - top, width, CELL_HEIGHT,
+        color: style[:background] || "#0000", border_color: style[:border_color] || "#B8BEC8",
+        border_width: style[:border_width] || 0.5)
       text = text.to_s.lines.first.to_s.chomp
       text = text.encode(Encoding::UTF_8)
       # ponytail: fixed-height PDF rows cap text at 13pt; variable page geometry can lift the ceiling.
@@ -111,8 +127,15 @@ module Rukbat
         when :bottom then y + 2
         else y + (CELL_HEIGHT - size) / 2
         end
-        page.text(text, x: text_x, y: baseline, font: font, size: size,
-          color: rgb(style[:color] || "#20242C"), bold: style[:bold] || false, italic: style[:italic] || false)
+        color = style[:color] || "#20242C"
+        if style[:bold] || style[:italic]
+          # GlyphRun has no synthetic-style fields; retain Okab's searchable
+          # faux-bold/italic text operator for those cells only.
+          styled_text << [text, text_x, baseline, font, size, rgb(color), !!style[:bold], !!style[:italic]]
+        else
+          renderer.paint_line(scene, renderer.layout_line(text, font: font.face, size: size),
+            x: text_x, y: PAGE_HEIGHT - baseline, color: color)
+        end
       end
     end
     private_class_method :paint_cell

data/lib/rukbat/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rukbat
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/rukbat/workbook.rb

@@ -10,7 +10,10 @@ module Rukbat
     MAX_FORMAT_CELLS = 100_000
     MAX_HIDDEN_CELLS = 100_000
     MAX_FILTER_ROWS = 100_000
+    MAX_PIVOT_ROWS = 100_000
+    MAX_PIVOT_GROUPS = 10_000
     MAX_CONDITIONAL_FORMATS = 256
+    MAX_INPUT_VALIDATIONS = 256
     FORMAT_KEYS = %i[number_format font_family font_size bold italic color background border_color border_width horizontal_alignment vertical_alignment].freeze
     CONDITIONAL_OPERATORS = %i[greater_than greater_than_or_equal less_than less_than_or_equal equal not_equal contains].freeze
     COLORS = {black: "#000000", blue: "#0000FF", cyan: "#00FFFF", green: "#008000",
@@ -22,6 +25,8 @@ module Rukbat
         row.between?(top, bottom) && column.between?(left, right)
       end
     end
+    InputValidation = Data.define(:area, :minimum, :maximum)
+    PivotTable = Data.define(:source_area, :row_key_column, :value_column, :aggregate, :headers, :rows)
 
     attr_reader :active_sheet
 
@@ -46,6 +51,7 @@ module Rukbat
       @hidden_columns = {}.freeze
       @frozen_panes = {name => {rows: 1, columns: 1}.freeze}.freeze
       @print_areas = {}.freeze
+      @input_validations = [].freeze
       @change_observers = []
       @source = CellSource.new(self)
       @engine = Furud::Engine.new(@source)
@@ -100,6 +106,7 @@ module Rukbat
       @formats = @formats.reject { |(sheet_name, _row, _column), _style| sheet_name == name }.freeze
       @comments = @comments.reject { |(sheet_name, _row, _column), _text| sheet_name == name }.freeze
       @conditional_formats = @conditional_formats.reject { |rule| rule[:area].sheet == name }.freeze
+      @input_validations = @input_validations.reject { |rule| rule.area.sheet == name }.freeze
       @hidden_rows = @hidden_rows.reject { |sheet_name, _| sheet_name == name }.freeze
       @hidden_columns = @hidden_columns.reject { |sheet_name, _| sheet_name == name }.freeze
       @frozen_panes = @frozen_panes.reject { |sheet_name, _| sheet_name == name }.freeze
@@ -129,15 +136,26 @@ module Rukbat
     def set(row, column, value, sheet: @active_sheet)
       ref = reference(row, column, sheet)
       current = input_at(row, column, sheet: ref.sheet)
-      return self if current == value
       return clear(row, column, sheet: ref.sheet) if value.nil?
 
       validate_formula(value, ref)
+      if current == value
+        validate_input_values!([ref])
+        return self
+      end
+
       updated = update_sheet(@sheets.fetch(ref.sheet), [[row - 1, column - 1, value]])
-      record_history
       @engine.set(ref, value)
+      changed = @engine.recalculate
+      begin
+        validate_input_values!([ref, *changed])
+      rescue Error
+        rebuild_engine
+        raise
+      end
+      record_history
       @sheets[ref.sheet] = updated
-      update_calculated(@engine.recalculate)
+      update_calculated(changed)
       notify_cells_changed(ref.sheet, [[ref.row, ref.column].freeze])
       self
     end
@@ -158,12 +176,14 @@ module Rukbat
         validate_formula(value, cell)
         [[row, column, value], cell, value] if current[row - 1, column - 1] != value
       end
-      return self if changes_to_apply.empty?
+      if changes_to_apply.empty?
+        validate_input_values!(values.values.map(&:first))
+        return self
+      end
 
       updated = update_sheet(current, changes_to_apply.map do |(row, column, value), _cell, _input|
         [row - 1, column - 1, value]
       end)
-      record_history
       changes_to_apply.each do |_change, cell, value|
         if value.nil?
           @engine.clear(cell)
@@ -171,8 +191,16 @@ module Rukbat
           @engine.set(cell, value)
         end
       end
+      changed = @engine.recalculate
+      begin
+        validate_input_values!([*changes_to_apply.map { |_change, cell, _value| cell }, *changed])
+      rescue Error
+        rebuild_engine
+        raise
+      end
+      record_history
       @sheets[ref.sheet] = updated
-      update_calculated(@engine.recalculate)
+      update_calculated(changed)
       notify_cells_changed(ref.sheet, changes_to_apply.map do |_change, cell, _value|
         [cell.row, cell.column].freeze
       end)
@@ -183,14 +211,64 @@ module Rukbat
       ref = reference(row, column, sheet)
       return self if input_at(row, column, sheet: ref.sheet).nil?
 
+      @engine.clear(ref)
+      changed = @engine.recalculate
+      begin
+        validate_input_values!([ref, *changed])
+      rescue Error
+        rebuild_engine
+        raise
+      end
       record_history
       @sheets[ref.sheet] = @sheets.fetch(ref.sheet).delete(row - 1, column - 1)
-      @engine.clear(ref)
-      update_calculated(@engine.recalculate)
+      update_calculated(changed)
       notify_cells_changed(ref.sheet, [[ref.row, ref.column].freeze])
       self
     end
 
+    def set_whole_number_validation(top, left, bottom, right, minimum:, maximum:, sheet: @active_sheet)
+      top, left, bottom, right, name = range_coordinates(top, left, bottom, right, sheet)
+      minimum, maximum = strict_integer(minimum), strict_integer(maximum)
+      raise Error, "minimum must not exceed maximum" if minimum > maximum
+
+      area = Furud::Area.new(sheet: name, top: top, left: left, bottom: bottom, right: right)
+      validation = InputValidation.new(area: area, minimum: minimum, maximum: maximum)
+      updated = @input_validations.flat_map do |existing|
+        existing.area.sheet == name ? subtract_input_validation(existing, top, left, bottom, right) : [existing]
+      end
+      updated << validation
+      raise Error, "input validation limit exceeded" if updated.length > MAX_INPUT_VALIDATIONS
+      return self if updated == @input_validations
+
+      record_history
+      @input_validations = updated.freeze
+      self
+    rescue ArgumentError, TypeError
+      raise Error, "validation limits must be integers"
+    end
+
+    def clear_input_validation(top, left, bottom, right, sheet: @active_sheet)
+      top, left, bottom, right, name = range_coordinates(top, left, bottom, right, sheet)
+      updated = @input_validations.flat_map do |existing|
+        existing.area.sheet == name ? subtract_input_validation(existing, top, left, bottom, right) : [existing]
+      end
+      raise Error, "input validation limit exceeded" if updated.length > MAX_INPUT_VALIDATIONS
+      return self if updated == @input_validations
+
+      record_history
+      @input_validations = updated.freeze
+      self
+    end
+
+    def input_validation_at(row, column, sheet: @active_sheet)
+      ref = reference(row, column, sheet)
+      @input_validations.find do |validation|
+        area = validation.area
+        area.sheet == ref.sheet && ref.row.between?(area.top, area.bottom) &&
+          ref.column.between?(area.left, area.right)
+      end
+    end
+
     def each_in(top, left, bottom, right, sheet: @active_sheet, &block)
       return enum_for(__method__, top, left, bottom, right, sheet: sheet) unless block
 
@@ -213,6 +291,104 @@ module Rukbat
         types: values.types)
     end
 
+    def pivot_table(top, left, bottom, right, row_key_column:, value_column:, aggregate: :sum, sheet: @active_sheet)
+      top, left, bottom, right, name = range_coordinates(top, left, bottom, right, sheet)
+      row_key_column, value_column = strict_integer(row_key_column), strict_integer(value_column)
+      width = right - left + 1
+      raise Error, "pivot row-key column must be between 1 and #{width}" unless row_key_column.between?(1, width)
+      raise Error, "pivot value column must be between 1 and #{width}" unless value_column.between?(1, width)
+      raise Error, "pivot aggregate must be :sum or :count" unless %i[sum count].include?(aggregate)
+      raise Error, "pivot source exceeds #{MAX_PIVOT_ROWS} data rows" if bottom - top > MAX_PIVOT_ROWS
+
+      key_column, measure_column = left + row_key_column - 1, left + value_column - 1
+      groups, keys = {}, []
+      ((top + 1)..bottom).each do |row|
+        key = @engine.value(Furud::Reference.new(sheet: name, row: row, column: key_column))
+        value = @engine.value(Furud::Reference.new(sheet: name, row: row, column: measure_column))
+        unless groups.key?(key)
+          raise Error, "pivot exceeds #{MAX_PIVOT_GROUPS} groups" if groups.length >= MAX_PIVOT_GROUPS
+
+          keys << (key.is_a?(String) ? key.dup.freeze : key)
+          groups[key] = 0
+        end
+        if aggregate == :count
+          groups[key] += 1 unless value.nil?
+        elsif finite_pivot_number?(value)
+          sum = groups[key] + value
+          raise Error, "pivot sum is not finite" unless finite_pivot_number?(sum)
+
+          groups[key] = sum
+        end
+      end
+
+      key_header = @engine.value(Furud::Reference.new(sheet: name, row: top, column: key_column))
+      value_header = @engine.value(Furud::Reference.new(sheet: name, row: top, column: measure_column))
+      key_header = "Column #{row_key_column}" if key_header.nil? || key_header.to_s.empty?
+      value_header = "Column #{value_column}" if value_header.nil? || value_header.to_s.empty?
+      headers = [key_header.to_s, "#{aggregate.to_s.capitalize} of #{value_header}"].freeze
+      rows = keys.map { |key| [key, groups.fetch(key)].freeze }.freeze
+      area = Furud::Area.new(sheet: name, top: top, left: left, bottom: bottom, right: right)
+      PivotTable.new(source_area: area, row_key_column: row_key_column,
+        value_column: value_column, aggregate: aggregate, headers: headers, rows: rows)
+    rescue ArgumentError, TypeError
+      raise Error, "pivot columns must be integers"
+    end
+
+    def add_pivot_sheet(name, pivot)
+      name = validate_name(name)
+      raise Error, "sheet already exists: #{name}" if @sheets.key?(name)
+      raise Error, "pivot must be a PivotTable" unless pivot.is_a?(PivotTable)
+      raise Error, "pivot source area is invalid" unless pivot.source_area.is_a?(Furud::Area)
+      raise Error, "unknown pivot source sheet: #{pivot.source_area.sheet}" unless @sheets.key?(pivot.source_area.sheet)
+      range_coordinates(pivot.source_area.top, pivot.source_area.left,
+        pivot.source_area.bottom, pivot.source_area.right, pivot.source_area.sheet)
+      source_width = pivot.source_area.right - pivot.source_area.left + 1
+      raise Error, "pivot columns are invalid" unless
+        pivot.row_key_column.is_a?(Integer) && pivot.row_key_column.between?(1, source_width) &&
+        pivot.value_column.is_a?(Integer) && pivot.value_column.between?(1, source_width) &&
+        %i[sum count].include?(pivot.aggregate)
+      raise Error, "pivot must have two headers and at most #{MAX_PIVOT_GROUPS} groups" unless
+        pivot.headers.is_a?(Array) && pivot.headers.length == 2 && pivot.rows.is_a?(Array) &&
+        pivot.rows.length <= MAX_PIVOT_GROUPS
+
+      rows = pivot.rows.each_with_index.map do |row, index|
+        raise Error, "pivot row #{index + 1} must contain a key and value" unless row.is_a?(Array) && row.length == 2
+
+        [row[0], row[1]]
+      end
+      changes = pivot.headers.each_with_index.map { |value, column| [1, column + 1, value] }
+      rows.each_with_index do |(key, value), index|
+        changes << [index + 2, 1, key]
+        changes << [index + 2, 2, value]
+      end
+      prepared = changes.map do |row, column, value|
+        row, column = strict_integer(row), strict_integer(column)
+        raise Error, "pivot output exceeds sheet limits" unless row.between?(1, MAX_ROWS) && column.between?(1, MAX_COLUMNS)
+
+        ref = Furud::Reference.new(sheet: name, row: row, column: column)
+        input = pivot_cell_input(value)
+        validate_formula(input, ref)
+        [row - 1, column - 1, input, ref]
+      end
+      updated = update_sheet(Denebola::Sheet.new, prepared.map { |row, column, value, _ref| [row, column, value] })
+      previous_state = snapshot
+      begin
+        @sheets = @sheets.merge(name => updated)
+        @calculated = @calculated.merge(name => Denebola::Sheet.new)
+        @frozen_panes = @frozen_panes.merge(name => {rows: 1, columns: 1}.freeze).freeze
+        prepared.each { |_row, _column, value, ref| @engine.set(ref, value) unless value.nil? }
+        changed = @engine.recalculate
+      rescue StandardError => error
+        restore(previous_state)
+        raise Error, "could not create pivot sheet: #{error.message}"
+      end
+      @history << previous_state
+      @redo.clear
+      update_calculated(changed)
+      notify_cells_changed(nil)
+      name
+    end
+
     def define_name(name, top, left, bottom, right, sheet: @active_sheet)
       name = name.to_s
       ast = Furud::Formula.parse("=#{name}")
@@ -348,7 +524,7 @@ module Rukbat
         named_ranges = named_ranges.map { |area| area.sheet == name ? adjusted_area(area, adjustment) : area }
         raise Error, "cannot delete an entire named range" if named_ranges.any?(&:nil?)
       end
-      record_history
+      previous_state = snapshot
       runs.each do |at, count|
         @engine.delete_rows(name, at, count)
         @sheets[name] = @sheets.fetch(name).delete_rows(at - 1, count)
@@ -357,7 +533,16 @@ module Rukbat
         adjust_metadata(:delete_rows, at, count, name)
       end
       sync_formula_inputs
-      update_calculated(@engine.recalculate)
+      changed = @engine.recalculate
+      begin
+        validate_input_values!(changed)
+      rescue Error
+        restore(previous_state)
+        raise
+      end
+      @history << previous_state
+      @redo.clear
+      update_calculated(changed)
       notify_cells_changed(name)
       duplicates.length
     end
@@ -635,6 +820,63 @@ module Rukbat
       raise Error, "row and column must be integers"
     end
 
+    def validate_input_values!(references)
+      references.uniq.each do |ref|
+        validation = input_validation_at(ref.row, ref.column, sheet: ref.sheet)
+        next unless validation
+
+        value = @engine.value(ref)
+        next if value.nil?
+
+        whole_number = value.is_a?(Integer) || (value.is_a?(Float) && value.finite? && value == value.to_i)
+        next if whole_number && value >= validation.minimum && value <= validation.maximum
+
+        address = "#{Furud::Formula.column_name(ref.column)}#{ref.row}"
+        raise Error, "#{address} must be a whole number between #{validation.minimum} and #{validation.maximum}"
+      end
+    end
+
+    def finite_pivot_number?(value)
+      value.is_a?(Numeric) && !value.is_a?(Complex) && (!value.respond_to?(:finite?) || value.finite?)
+    end
+
+    def pivot_cell_input(value)
+      case value
+      when String
+        value.start_with?("=") ? "=#{Furud::Formula.render_literal(value)}" : value
+      when Float
+        value.finite? ? value : value.to_s
+      when Complex
+        value.to_s
+      when NilClass, TrueClass, FalseClass, Numeric, Furud::ErrorValue
+        value
+      else
+        value.to_s
+      end
+    rescue StandardError => error
+      raise Error, "pivot value cannot be written: #{error.message}"
+    end
+
+    def subtract_input_validation(validation, top, left, bottom, right)
+      area = validation.area
+      intersect_top, intersect_left = [area.top, top].max, [area.left, left].max
+      intersect_bottom, intersect_right = [area.bottom, bottom].min, [area.right, right].min
+      return [validation] if intersect_top > intersect_bottom || intersect_left > intersect_right
+
+      ranges = []
+      ranges << [area.top, area.left, intersect_top - 1, area.right] if area.top < intersect_top
+      ranges << [intersect_bottom + 1, area.left, area.bottom, area.right] if intersect_bottom < area.bottom
+      ranges << [intersect_top, area.left, intersect_bottom, intersect_left - 1] if area.left < intersect_left
+      ranges << [intersect_top, intersect_right + 1, intersect_bottom, area.right] if intersect_right < area.right
+      ranges.map do |range_top, range_left, range_bottom, range_right|
+        InputValidation.new(
+          area: Furud::Area.new(sheet: area.sheet, top: range_top, left: range_left,
+            bottom: range_bottom, right: range_right),
+          minimum: validation.minimum, maximum: validation.maximum
+        )
+      end
+    end
+
     def range_coordinates(top, left, bottom, right, name)
       top, left, bottom, right = [top, left, bottom, right].map { |value| strict_integer(value) }
       name = (name || @active_sheet).to_s
@@ -665,7 +907,7 @@ module Rukbat
       raise Error, "index is outside sheet limits" unless at.between?(1, extent)
       preflight_structural_edit(type, at, count, name, extent)
 
-      record_history
+      previous_state = snapshot
       @engine.public_send(type, name, at, count)
       denebola_at = at - 1
       current = @sheets.fetch(name)
@@ -676,7 +918,16 @@ module Rukbat
       @calculated[name] = calculated.public_send(type, denebola_at, count) if denebola_at <= calculated_extent
       adjust_metadata(type, at, count, name)
       sync_formula_inputs
-      update_calculated(@engine.recalculate)
+      changed = @engine.recalculate
+      begin
+        validate_input_values!(changed)
+      rescue Error
+        restore(previous_state)
+        raise
+      end
+      @history << previous_state
+      @redo.clear
+      update_calculated(changed)
       notify_cells_changed(name)
       self
     rescue ArgumentError, TypeError
@@ -709,10 +960,12 @@ module Rukbat
     end
 
     def snapshot = [@sheets.dup, @active_sheet, @names.dup, @formats.dup, @comments.dup,
-      @conditional_formats.dup, @hidden_rows.dup, @hidden_columns.dup, @frozen_panes.dup, @print_areas.dup]
+      @conditional_formats.dup, @hidden_rows.dup, @hidden_columns.dup, @frozen_panes.dup, @print_areas.dup,
+      @input_validations.dup]
 
     def restore(state)
-      @sheets, @active_sheet, @names, @formats, @comments, @conditional_formats, @hidden_rows, @hidden_columns, @frozen_panes, @print_areas = state
+      @sheets, @active_sheet, @names, @formats, @comments, @conditional_formats, @hidden_rows,
+        @hidden_columns, @frozen_panes, @print_areas, @input_validations = state
       rebuild_engine
     end
 
@@ -817,11 +1070,16 @@ module Rukbat
         next unless area.sheet == name
         type.to_s.end_with?("rows") ? area.bottom : area.right
       end.max || 0
+      validation_extent = @input_validations.filter_map do |rule|
+        area = rule.area
+        next unless area.sheet == name
+        type.to_s.end_with?("rows") ? area.bottom : area.right
+      end.max || 0
       print_extent = @print_areas.values.filter_map do |area|
         next unless area.sheet == name
         type.to_s.end_with?("rows") ? area.bottom : area.right
       end.max || 0
-      area_extent = [area_extent, print_extent].max
+      area_extent = [area_extent, print_extent, validation_extent].max
       hidden_extent = (type.to_s.end_with?("rows") ? @hidden_rows : @hidden_columns)
         .fetch(name, Set.new).max || 0
       panes = @frozen_panes.fetch(name, {rows: 1, columns: 1})
@@ -909,6 +1167,10 @@ module Rukbat
         area = adjusted_area(rule[:area], operation)
         area && rule.merge(area: area).freeze
       end.freeze
+      @input_validations = @input_validations.filter_map do |validation|
+        area = adjusted_area(validation.area, operation)
+        InputValidation.new(area: area, minimum: validation.minimum, maximum: validation.maximum) if area
+      end.freeze
       @print_areas = @print_areas.filter_map do |sheet_name, area|
         adjusted = sheet_name == sheet ? adjusted_area(area, operation) : area
         [sheet_name, adjusted] if adjusted

data/sig/rukbat.rbs

@@ -14,6 +14,15 @@ module Rukbat
   class Workbook
     MAX_ROWS: Integer
     MAX_COLUMNS: Integer
+    MAX_INPUT_VALIDATIONS: Integer
+    MAX_PIVOT_ROWS: Integer
+    MAX_PIVOT_GROUPS: Integer
+
+    class InputValidation
+      attr_reader area: Furud::Area
+      attr_reader minimum: Integer
+      attr_reader maximum: Integer
+    end
 
     class CellRange
       attr_reader top: Integer
@@ -33,6 +42,15 @@ module Rukbat
       attr_reader types: Hash[Class, Integer]
     end
 
+    class PivotTable
+      attr_reader source_area: Furud::Area
+      attr_reader row_key_column: Integer
+      attr_reader value_column: Integer
+      attr_reader aggregate: :sum | :count
+      attr_reader headers: [String, String]
+      attr_reader rows: Array[[untyped, untyped]]
+    end
+
     attr_reader active_sheet: String
 
     def self.from_rows: (Enumerable[Array[untyped]] rows, ?sheet: String) -> Workbook
@@ -50,9 +68,14 @@ module Rukbat
     def set: (Integer row, Integer column, untyped value, ?sheet: String) -> self
     def set_many: (Enumerable[Array[untyped]] changes, ?sheet: String) -> self
     def clear: (Integer row, Integer column, ?sheet: String) -> self
+    def set_whole_number_validation: (Integer top, Integer left, Integer bottom, Integer right, minimum: Integer, maximum: Integer, ?sheet: String) -> self
+    def clear_input_validation: (Integer top, Integer left, Integer bottom, Integer right, ?sheet: String) -> self
+    def input_validation_at: (Integer row, Integer column, ?sheet: String) -> InputValidation?
     def each_in: (Integer top, Integer left, Integer bottom, Integer right, ?sheet: String) -> Enumerator[[Furud::Reference, untyped], self]
               | (Integer top, Integer left, Integer bottom, Integer right, ?sheet: String) { (Furud::Reference reference, untyped value) -> void } -> self
     def summary: (Integer top, Integer left, Integer bottom, Integer right, ?sheet: String) -> Summary
+    def pivot_table: (Integer top, Integer left, Integer bottom, Integer right, row_key_column: Integer, value_column: Integer, ?aggregate: :sum | :count, ?sheet: String) -> PivotTable
+    def add_pivot_sheet: (String name, PivotTable pivot) -> String
     def define_name: (String name, Integer top, Integer left, Integer bottom, Integer right, ?sheet: String) -> Furud::Area
     def find: (String query, ?top: Integer, ?left: Integer, ?bottom: Integer, ?right: Integer, ?sheet: String) -> Array[Furud::Reference]
     def filter_rows: (Integer top, Integer bottom, by: Integer, query: String, ?sheet: String) -> Array[Integer]
@@ -100,6 +123,8 @@ module Rukbat
   end
 
   class GridView
+    attr_reader validation_min_field: untyped
+    attr_reader validation_max_field: untyped
     def initialize: (Workbook workbook, ?on_save: untyped) -> void
     def undo: () -> bool
     def redo: () -> bool

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rukbat
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: spica
   requirement: !ruby/object:Gem::Requirement
@@ -142,14 +142,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.9.0
 description: A Ruby spreadsheet app built on persistent sparse sheets and the Furud
   calculation engine.
 email: