New Scale syntax and implementation (#82)

Author: thomasp85

CLAUDE.md

@@ -10,7 +10,7 @@
 SELECT date, revenue, region FROM sales WHERE year = 2024
 VISUALISE date AS x, revenue AS y, region AS color
 DRAW line
-SCALE x SETTING type => 'date'
+SCALE x VIA date
 COORD cartesian SETTING ylim => [0, 100000]
 LABEL title => 'Sales by Region', x => 'Date', y => 'Revenue'
 THEME minimal
@@ -243,7 +243,7 @@ For detailed API documentation, see [`src/doc/API.md`](src/doc/API.md).
 
 - Uses `tree-sitter-ggsql` grammar (507 lines, simplified approach)
 - Parses **full query** (SQL + VISUALISE) into concrete syntax tree (CST)
-- Grammar supports: PLOT/TABLE/MAP types, DRAW/SCALE/FACET/COORD/LABEL/GUIDE/THEME clauses
+- Grammar supports: PLOT/TABLE/MAP types, DRAW/SCALE/FACET/COORD/LABEL/THEME clauses
 - British and American spellings: `VISUALISE` / `VISUALIZE`
 - **SQL portion parsing**: Basic SQL structure (SELECT, WITH, CREATE, INSERT, subqueries)
 - **Recursive subquery support**: Fully recursive grammar for complex SQL
@@ -288,7 +288,6 @@ pub struct Plot {
     pub facet: Option<Facet>,          // FACET clause
     pub coord: Option<Coord>,          // COORD clause
     pub labels: Option<Labels>,        // LABEL clause
-    pub guides: Vec<Guide>,            // GUIDE clauses
     pub theme: Option<Theme>,          // THEME clause
 }
 
@@ -395,19 +394,6 @@ pub struct Labels {
     pub labels: HashMap<String, String>,  // label type → text
 }
 
-pub struct Guide {
-    pub aesthetic: String,
-    pub guide_type: Option<GuideType>,
-    pub properties: HashMap<String, ParameterValue>,
-}
-
-pub enum GuideType {
-    Legend,
-    ColorBar,
-    Axis,
-    None,
-}
-
 pub struct Theme {
     pub style: Option<String>,
     pub properties: HashMap<String, ParameterValue>,
@@ -421,7 +407,6 @@ pub struct Theme {
 - `Plot::new()` - Create a new empty Plot
 - `Plot::with_global_mapping(mapping)` - Create Plot with a global mapping
 - `Plot::find_scale(aesthetic)` - Look up scale specification for an aesthetic
-- `Plot::find_guide(aesthetic)` - Find a guide specification for an aesthetic
 - `Plot::has_layers()` - Check if Plot has any layers
 - `Plot::layer_count()` - Get the number of layers
 
@@ -781,7 +766,7 @@ SELECT * FROM (VALUES
 SELECT * FROM sales
 VISUALISE
 DRAW line MAPPING date AS x, revenue AS y, region AS color
-SCALE x SETTING type => 'date'
+SCALE x VIA date
 LABEL title => 'Sales Trends'
 ```
 
@@ -1093,16 +1078,15 @@ Where `<global_mapping>` can be:
 
 ### Clause Types
 
-| Clause      | Repeatable | Purpose            | Example                                   |
-| ----------- | ---------- | ------------------ | ----------------------------------------- |
-| `VISUALISE` | ✅ Yes     | Entry point        | `VISUALISE date AS x, revenue AS y`       |
-| `DRAW`      | ✅ Yes     | Define layers      | `DRAW line MAPPING date AS x, value AS y` |
-| `SCALE`     | ✅ Yes     | Configure scales   | `SCALE x SETTING type => 'date'`          |
-| `FACET`     | ❌ No      | Small multiples    | `FACET WRAP region`                       |
-| `COORD`     | ❌ No      | Coordinate system  | `COORD cartesian SETTING xlim => [0,100]` |
-| `LABEL`     | ❌ No      | Text labels        | `LABEL title => 'My Chart', x => 'Date'`  |
-| `GUIDE`     | ✅ Yes     | Legend/axis config | `GUIDE color SETTING position => 'right'` |
-| `THEME`     | ❌ No      | Visual styling     | `THEME minimal`                           |
+| Clause         | Repeatable | Purpose            | Example                              |
+| -------------- | ---------- | ------------------ | ------------------------------------ |
+| `VISUALISE`    | ✅ Yes     | Entry point        | `VISUALISE date AS x, revenue AS y`  |
+| `DRAW`         | ✅ Yes     | Define layers      | `DRAW line MAPPING date AS x, value AS y` |
+| `SCALE`        | ✅ Yes     | Configure scales   | `SCALE x VIA date`                            |
+| `FACET`        | ❌ No      | Small multiples    | `FACET WRAP region`                  |
+| `COORD`        | ❌ No      | Coordinate system  | `COORD cartesian SETTING xlim => [0,100]` |
+| `LABEL`        | ❌ No      | Text labels        | `LABEL title => 'My Chart', x => 'Date'`   |
+| `THEME`        | ❌ No      | Visual styling     | `THEME minimal`                      |
 
 ### DRAW Clause (Layers)
 
@@ -1214,49 +1198,79 @@ DRAW line
 **Syntax**:
 
 ```sql
-SCALE <aesthetic> SETTING
-  [type => <scale_type>]
-  [limits => [min, max]]
-  [breaks => <array | interval>]
-  [palette => <name>]
-  [domain => [values...]]
+SCALE [TYPE] <aesthetic> [FROM <input>] [TO <output>] [VIA <transform>] [SETTING <properties>]
 ```
 
-**Scale Types**:
+**Type Modifiers** (optional, placed before aesthetic):
 
-- **Continuous**: `linear`, `log10`, `log`, `log2`, `sqrt`, `reverse`
-- **Discrete**: `categorical`, `ordinal`
-- **Temporal**: `date`, `datetime`, `time`
-- **Color Palettes**: `viridis`, `plasma`, `magma`, `inferno`, `cividis`, `diverging`, `sequential`
+- **`CONTINUOUS`** - Continuous numeric data
+- **`DISCRETE`** - Categorical/discrete data
+- **`BINNED`** - Binned/bucketed data
+- **`DATE`** - Date data (maps to Vega-Lite temporal type)
+- **`DATETIME`** - Datetime data (maps to Vega-Lite temporal type)
+
+**Subclauses**:
+
+- **`FROM [...]`** - Input range specification (maps to Vega-Lite `scale.domain`)
+- **`TO [...]`** or **`TO palette`** - Output range as array or named palette (maps to Vega-Lite `scale.range` or `scale.scheme`)
+- **`VIA transform`** - Transformation method (reserved for future use)
+- **`SETTING ...`** - Additional properties (e.g., `breaks`)
+
+**Named Palettes** (used with `TO`):
+
+- `viridis`, `plasma`, `magma`, `inferno`, `cividis`, `diverging`, `sequential`
 
 **Critical for Date Formatting**:
 
 ```sql
-SCALE x SETTING type => 'date'
+SCALE x VIA date
 -- Maps to Vega-Lite field type = "temporal"
 -- Enables proper date axis formatting
 ```
 
-**Domain Property**:
+**Input Range Specification** (FROM clause):
 
-The `domain` property explicitly sets the input domain for a scale:
+The `FROM` clause explicitly sets the input range for a scale:
 
 ```sql
--- Set domain for discrete scale
-SCALE color SETTING domain => ['red', 'green', 'blue']
+-- Set range for discrete scale
+SCALE DISCRETE color FROM ['A', 'B', 'C']
 
--- Set domain for continuous scale
-SCALE x SETTING domain => [0, 100]
+-- Set range for continuous scale
+SCALE CONTINUOUS x FROM [0, 100]
 ```
 
-**Note**: Cannot specify domain in both SCALE and COORD for the same aesthetic (will error).
+**Range Specification** (TO clause):
 
-**Example**:
+The `TO` clause sets the output range - either explicit values or a named palette:
 
 ```sql
-SCALE x SETTING type => 'date', breaks => '2 months'
-SCALE y SETTING type => 'log10', limits => [1, 1000]
-SCALE color SETTING palette => 'viridis', domain => ['A', 'B', 'C']
+-- Explicit color values
+SCALE color FROM ['A', 'B'] TO ['red', 'blue']
+
+-- Named palette
+SCALE color TO viridis
+```
+
+**Note**: Cannot specify range in both SCALE and COORD for the same aesthetic (will error).
+
+**Examples**:
+
+```sql
+-- Date scale
+SCALE x VIA date
+
+-- Continuous scale with input range
+SCALE CONTINUOUS y FROM [0, 100]
+
+-- Discrete color scale with input range and output range
+SCALE DISCRETE color FROM ['A', 'B', 'C'] TO ['red', 'green', 'blue']
+
+-- Color scale with named palette
+SCALE color TO viridis
+
+-- Scale with input range and additional settings
+SCALE x VIA date FROM ['2024-01-01', '2024-12-31'] SETTING breaks => '1 month'
 ```
 
 ### FACET Clause
@@ -1313,22 +1327,22 @@ COORD SETTING <properties>
 
 - `xlim => [min, max]` - Set x-axis limits
 - `ylim => [min, max]` - Set y-axis limits
-- `<aesthetic> => [values...]` - Set domain for any aesthetic (color, fill, size, etc.)
+- `<aesthetic> => [values...]` - Set range for any aesthetic (color, fill, size, etc.)
 
 **Flip**:
 
-- `<aesthetic> => [values...]` - Set domain for any aesthetic
+- `<aesthetic> => [values...]` - Set range for any aesthetic
 
 **Polar**:
 
 - `theta => <aesthetic>` - Which aesthetic maps to angle (defaults to `y`)
-- `<aesthetic> => [values...]` - Set domain for any aesthetic
+- `<aesthetic> => [values...]` - Set range for any aesthetic
 
 **Important Notes**:
 
 1. **Axis limits auto-swap**: `xlim => [100, 0]` automatically becomes `[0, 100]`
 2. **ggplot2 compatibility**: `coord_flip` preserves axis label names (labels stay with aesthetic names, not visual position)
-3. **Domain conflicts**: Error if same aesthetic has domain in both SCALE and COORD
+3. **Range conflicts**: Error if same aesthetic has input range in both SCALE and COORD
 4. **Multi-layer support**: All coordinate transforms apply to all layers
 
 **Status**:
@@ -1344,7 +1358,7 @@ COORD SETTING <properties>
 -- Cartesian with axis limits
 COORD cartesian SETTING xlim => [0, 100], ylim => [0, 50]
 
--- Cartesian with aesthetic domain
+-- Cartesian with aesthetic range
 COORD cartesian SETTING color => O ['red', 'green', 'blue']
 
 -- Cartesian shorthand (type optional when using SETTING)
@@ -1353,7 +1367,7 @@ COORD SETTING xlim => [0, 100]
 -- Flip coordinates for horizontal bar chart
 COORD flip
 
--- Flip with aesthetic domain
+-- Flip with aesthetic range
 COORD flip SETTING color => ['A', 'B', 'C']
 
 -- Polar for pie chart (theta defaults to y)
@@ -1427,7 +1441,7 @@ DRAW line
     MAPPING sale_date AS x, total AS y, region AS color
 DRAW point
     MAPPING sale_date AS x, total AS y, region AS color
-SCALE x SETTING type => 'date'
+SCALE x VIA date
 FACET WRAP region
 LABEL title => 'Sales Trends by Region', x => 'Date', y => 'Total Quantity'
 THEME minimal

Cargo.toml

@@ -57,6 +57,9 @@ pyo3 = "0.26"
 # Testing
 proptest = "1.4"
 
+# Color interpolation
+palette = "0.7"
+
 # Utilities
 regex = "1.10"
 chrono = "0.4"

EXAMPLES.md

@@ -111,16 +111,16 @@ SCALE y SETTING type => 'log10'
 SELECT date, temperature, station FROM weather
 VISUALISE date AS x, temperature AS y, station AS color
 DRAW line
-SCALE color SETTING palette => 'viridis'
+SCALE color TO viridis
 ```
 
-### Custom Domain
+### Custom input range
 
 ```sql
 SELECT category, value FROM data
 VISUALISE category AS x, value AS y, category AS fill
 DRAW bar
-SCALE fill SETTING domain => ['A', 'B', 'C', 'D']
+SCALE DISCRETE fill FROM ['A', 'B', 'C', 'D']
 ```
 
 ---
@@ -470,7 +470,7 @@ WHERE timestamp >= NOW() - INTERVAL '7 days'
 VISUALISE timestamp AS x, temperature AS y, station AS color, station AS linetype
 DRAW line
 SCALE x SETTING type => 'datetime'
-SCALE color SETTING palette => 'viridis'
+SCALE color TO viridis
 LABEL title => 'Temperature Trends',
       x => 'Time',
       y => 'Temperature (°C)'
@@ -496,7 +496,7 @@ LABEL title => 'Top 10 Products by Revenue',
 THEME classic
 ```
 
-### Distribution with Custom Domain
+### Distribution with Custom range
 
 ```sql
 SELECT
@@ -508,7 +508,7 @@ WHERE category IN ('A', 'B', 'C')
 VISUALISE date AS x, value AS y, category AS color, value AS size
 DRAW point
 SCALE x SETTING type => 'date'
-SCALE color SETTING domain => ['A', 'B', 'C']
+SCALE DISCRETE color FROM ['A', 'B', 'C']
 SCALE size SETTING limits => [0, 100]
 COORD cartesian SETTING ylim => [0, 150]
 LABEL title => 'Measurement Distribution',
@@ -528,7 +528,7 @@ FROM data_points
 VISUALISE x, y, category AS color
 DRAW point SETTING size => 5
 DRAW text MAPPING label AS label
-SCALE color SETTING palette => 'viridis'
+SCALE color TO viridis
 COORD cartesian SETTING xlim => [0, 100], ylim => [0, 100]
 LABEL title => 'Annotated Scatter Plot',
       x => 'X Axis',
@@ -545,7 +545,7 @@ GROUP BY cyl
 ORDER BY cyl
 VISUALISE cyl AS x, vehicle_count AS y
 DRAW bar
-SCALE x SETTING domain => [4, 6, 8]
+SCALE DISCRETE x FROM [4, 6, 8]
 LABEL title => 'Distribution of Vehicles by Number of Cylinders',
       x => 'Number of Cylinders',
       y => 'Number of Vehicles'
@@ -640,7 +640,7 @@ Draw Line
 
 8. **Labels**: Always provide meaningful titles and axis labels for clarity.
 
-9. **Domain Specification**: Use either SCALE or COORD for domain/limit specification, but not both for the same aesthetic.
+9. **Range Specification**: Use either SCALE or COORD for range/limit specification, but not both for the same aesthetic.
 
 ---
 

README.md

@@ -219,7 +219,7 @@ Key grammar elements:
 - `SCALE <aesthetic> SETTING` - Configure data-to-visual mappings
 - `FACET` - Create small multiples (WRAP for flowing layout, BY for grid)
 - `COORD` - Coordinate transformations (cartesian, flip, polar)
-- `LABEL`, `THEME`, `GUIDE` - Styling and annotation
+- `LABEL`, `THEME` - Styling and annotation
 
 ## Jupyter Kernel
 

doc/_quarto.yml

@@ -18,7 +18,7 @@ website:
   announcement:
     icon: info-circle
     dismissable: true
-    content: "ggsql is still in early development and all functionality is subject to change"
+    content: "ggsql is still in early development and all functionality are subject to change"
     type: primary
     position: below-navbar
   twitter-card:
@@ -80,6 +80,14 @@ website:
       - section: Layers
         contents:
           - auto: syntax/layer/*
+      - section: Scales
+        contents:
+          - section: Types
+            contents:
+              - auto: syntax/scale/type/*
+          - section: Palettes
+            contents:
+              - auto: syntax/scale/palette/*
 
 
 format: