Merge commit '3bbed9d1ef0800239bfcaebd399d7c3b1745505b'

Author: thomasp85

CLAUDE.md

@@ -322,23 +322,39 @@ pub enum GlobalMappingItem {
 
 pub struct Layer {
     pub geom: Geom,                  // Geometric object type
+    pub position: Position,          // Position adjustment (from SETTING position)
     pub aesthetics: HashMap<String, AestheticValue>,  // Aesthetic mappings (from MAPPING)
     pub parameters: HashMap<String, ParameterValue>,  // Geom parameters (from SETTING)
+    pub source: Option<DataSource>,  // Data source (from MAPPING ... FROM or PLACE)
     pub filter: Option<FilterExpression>,  // Layer filter (from FILTER)
     pub partition_by: Vec<String>,   // Grouping columns (from PARTITION BY)
 }
 
 pub enum Geom {
     // Basic geoms
-    Point, Line, Path, Bar, Col, Area, Tile, Polygon, Ribbon,
+    Point, Line, Path, Bar, Col, Area, Rect, Polygon, Ribbon,
     // Statistical geoms
     Histogram, Density, Smooth, Boxplot, Violin,
     // Annotation geoms
-    Text, Label, Segment, Arrow, Rule, Linear, ErrorBar,
+    Text, Segment, Arrow, Rule, Linear, ErrorBar,
+}
+
+pub enum DataSource {
+    Identifier(String),  // Table/CTE name
+    FilePath(String),    // File path (quoted)
+    Annotation,          // PLACE clause (no external data)
+}
+
+pub enum Position {
+    Identity,  // No adjustment
+    Stack,     // Stack elements (bars, areas)
+    Dodge,     // Dodge side-by-side (bars)
+    Jitter,    // Jitter points randomly
 }
 
 pub enum AestheticValue {
-    Column(String),                  // Unquoted column reference: revenue AS x
+    Column(String),                  // Column from data: revenue AS x
+    AnnotationColumn(String),        // Annotation literal (PLACE): uses identity scale
     Literal(ParameterValue),         // Quoted literal: 'value' AS fill
 }
 
@@ -1178,6 +1194,7 @@ Where `<global_mapping>` can be:
 | ----------- | ---------- | ----------------- | ----------------------------------------- |
 | `VISUALISE` | ✅ Yes     | Entry point       | `VISUALISE date AS x, revenue AS y`       |
 | `DRAW`      | ✅ Yes     | Define layers     | `DRAW line MAPPING date AS x, value AS y` |
+| `PLACE`     | ✅ Yes     | Annotation layers | `PLACE point SETTING x => 5, y => 10`     |
 | `SCALE`     | ✅ Yes     | Configure scales  | `SCALE x VIA date`                        |
 | `FACET`     | ❌ No      | Small multiples   | `FACET region`                            |
 | `PROJECT`   | ❌ No      | Coordinate system | `PROJECT TO cartesian` |
@@ -1200,7 +1217,7 @@ All clauses (MAPPING, SETTING, PARTITION BY, FILTER) are optional.
 
 **Geom Types**:
 
-- **Basic**: `point`, `line`, `path`, `bar`, `col`, `area`, `tile`, `polygon`, `ribbon`
+- **Basic**: `point`, `line`, `path`, `bar`, `col`, `area`, `rect`, `polygon`, `ribbon`
 - **Statistical**: `histogram`, `density`, `smooth`, `boxplot`, `violin`
 - **Annotation**: `text`, `label`, `segment`, `arrow`, `rule`, `linear`, `errorbar`
 
@@ -1211,7 +1228,7 @@ Maps data values (columns or literals) to visual aesthetics. Syntax: `value AS a
 - **Position**: `x`, `y`, `xmin`, `xmax`, `ymin`, `ymax`
 - **Color**: `color`, `fill`, `stroke`, `opacity`
 - **Size/Shape**: `size`, `shape`, `linetype`, `linewidth`
-- **Text**: `label`, `family`, `fontface`
+- **Text**: `label`, `typeface`, `fontweight`, `italic`
 
 **Literal vs Column**:
 
@@ -1289,6 +1306,29 @@ DRAW line
     FILTER year >= 2020
 ```
 
+### PLACE Clause (Annotation Layers)
+
+**Syntax**:
+
+```sql
+PLACE <geom> SETTING <aesthetic/parameter> => <value>, ...
+```
+
+Creates annotation layers with literal values only (no data mappings). All aesthetics set via SETTING; supports arrays that are recycled to longest length. No FILTER/PARTITION BY/ORDER BY support.
+
+**Examples**:
+
+```sql
+-- Single annotation
+PLACE point SETTING x => 5, y => 10, color => 'red'
+
+-- Multiple annotations (array recycling)
+PLACE point SETTING x => [1, 2, 3], y => [10, 20, 30]
+
+-- Reference line
+PLACE rule SETTING x => 5, color => 'red'
+```
+
 ### SCALE Clause
 
 **Syntax**:

doc/_quarto.yml

@@ -40,6 +40,8 @@ website:
             href: syntax/clause/visualise.qmd
           - text: "`DRAW`"
             href: syntax/clause/draw.qmd
+          - text: "`PLACE`"
+            href: syntax/clause/place.qmd
           - text: "`SCALE`"
             href: syntax/clause/scale.qmd
           - text: "`FACET`"
@@ -77,6 +79,8 @@ website:
             href: syntax/clause/visualise.qmd
           - text: "`DRAW`"
             href: syntax/clause/draw.qmd
+          - text: "`PLACE`"
+            href: syntax/clause/place.qmd
           - text: "`SCALE`"
             href: syntax/clause/scale.qmd
           - text: "`FACET`"

doc/ggsql.xml

@@ -90,6 +90,7 @@
     <!-- ggsql Main Clause Keywords (triggers context switch) -->
     <list name="clause_keywords">
       <item>DRAW</item>
+      <item>PLACE</item>
       <item>SCALE</item>
       <item>PROJECT</item>
       <item>FACET</item>
@@ -129,7 +130,7 @@
       <item>bar</item>
       <item>col</item>
       <item>area</item>
-      <item>tile</item>
+      <item>rect</item>
       <item>polygon</item>
       <item>ribbon</item>
       <item>histogram</item>
@@ -168,8 +169,9 @@
       <item>linewidth</item>
       <item>width</item>
       <item>height</item>
-      <item>family</item>
-      <item>fontface</item>
+      <item>typeface</item>
+      <item>fontweight</item>
+      <item>italic</item>
       <item>hjust</item>
       <item>vjust</item>
     </list>
@@ -403,6 +405,7 @@
 
         <!-- Clause keywords trigger context switches -->
         <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
         <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>
@@ -450,6 +453,7 @@
 
         <!-- Exit to other clause contexts -->
         <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
         <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>
@@ -480,6 +484,46 @@
         <DetectChar char="," attribute="Symbol" context="#stay"/>
       </context>
 
+      <!-- PLACE clause context (annotation layers) -->
+      <context name="PlaceClause" attribute="Normal Text" lineEndContext="#stay">
+        <Detect2Chars char="-" char1="-" attribute="Comment" context="Comment"/>
+        <Detect2Chars char="/" char1="*" attribute="Comment" context="CommentMulti" beginRegion="comment"/>
+        <DetectChar char="'" attribute="String" context="StringSingle"/>
+        <DetectChar char="&quot;" attribute="String" context="StringDouble"/>
+        <RegExpr attribute="Number" context="#stay" String="-?[0-9]+\.?[0-9]*([eE][+-]?[0-9]+)?"/>
+
+        <!-- Exit to other clause contexts -->
+        <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="LabelClause" String="LABEL" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="ThemeClause" String="THEME" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="Normal" String="VISUALISE" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="Normal" String="VISUALIZE" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="Normal" String="SELECT" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="Normal" String="WHERE" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="Normal" String="WITH" insensitive="true"/>
+
+        <!-- Geom types - same as DRAW -->
+        <keyword attribute="Data Type" context="#stay" String="geoms"/>
+
+        <!-- Aesthetics -->
+        <keyword attribute="Attribute" context="#stay" String="aesthetics"/>
+
+        <!-- Sub-keywords (only SETTING supported, not FILTER/PARTITION/ORDER) -->
+        <WordDetect attribute="Keyword" context="#stay" String="SETTING" insensitive="true"/>
+
+        <StringDetect attribute="Operator" context="#stay" String="=&gt;"/>
+        <AnyChar attribute="Operator" context="#stay" String="=!&lt;&gt;+-*/%"/>
+        <DetectChar char="(" attribute="Symbol" context="#stay"/>
+        <DetectChar char=")" attribute="Symbol" context="#stay"/>
+        <DetectChar char="[" attribute="Symbol" context="#stay"/>
+        <DetectChar char="]" attribute="Symbol" context="#stay"/>
+        <DetectChar char="," attribute="Symbol" context="#stay"/>
+      </context>
+
       <!-- SCALE clause context -->
       <context name="ScaleClause" attribute="Normal Text" lineEndContext="#stay">
         <Detect2Chars char="-" char1="-" attribute="Comment" context="Comment"/>
@@ -490,6 +534,7 @@
 
         <!-- Exit to other clause contexts -->
         <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
         <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>
@@ -536,6 +581,7 @@
 
         <!-- Exit to other clause contexts -->
         <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
         <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>
@@ -579,6 +625,7 @@
 
         <!-- Exit to other clause contexts -->
         <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
         <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>
@@ -621,6 +668,7 @@
 
         <!-- Exit to other clause contexts -->
         <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
         <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>
@@ -658,6 +706,7 @@
 
         <!-- Exit to other clause contexts -->
         <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
         <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>
@@ -698,6 +747,7 @@
 
         <!-- Exit to other clause contexts -->
         <WordDetect attribute="Keyword" context="DrawClause" String="DRAW" insensitive="true"/>
+        <WordDetect attribute="Keyword" context="PlaceClause" String="PLACE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ScaleClause" String="SCALE" insensitive="true"/>
         <WordDetect attribute="Keyword" context="ProjectClause" String="PROJECT" insensitive="true"/>
         <WordDetect attribute="Keyword" context="FacetClause" String="FACET" insensitive="true"/>

doc/syntax/clause/place.qmd

@@ -0,0 +1,37 @@
+---
+title: "Create annotation layers with `PLACE`"
+---
+
+The `PLACE` clause is the little sibling of the [`DRAW` clause](draw.qmd) that also creates layers.
+A layer created with `PLACE` has no mappings to data, all aesthetics are set using literal values instead.
+
+## Clause syntax
+The `PLACE` clause takes just a type and a setting clause, all of them required.
+
+```ggsql
+PLACE <layer-type>
+    SETTING <parameter/aesthetic> => <value>, ...
+```
+
+Like `DRAW`, the layer type is required and specifies the type of layer to draw, like `point` or `text`.
+It defines how the remaining settings are interpreted. 
+The [main syntax page](../index.qmd#layers) has a list of all available layer types
+
+Unlike the `DRAW` clause, the `PLACE` clause does not support `FILTER`, `PARTITION BY`, and `ORDER BY` clauses since
+everything is declared inline.
+
+### `SETTING`
+```ggsql
+SETTING <parameter/aesthetic> => <value>, ...
+```
+
+The `SETTING` clause can be used for two different things:
+
+* *Setting aesthetics*: All aesthetics in `PLACE` layers are specified using literal value, e.g. 'red' (as in the color red). 
+Aesthetics that are set will not go through a scale but will use the provided value as-is. 
+You cannot set an aesthetic to a column, only to a literal values.
+Contrary to `DRAW` layers, `PLACE` layers can take multiple literal values in an array.
+* *Setting parameters*: Some layers take additional arguments that control how they behave. 
+Often, but not always, these modify the statistical transformation in some way. 
+An example would be the binwidth parameter in histogram which controls the width of each bin during histogram calculation. 
+This is not a statistical property since it is not related to each record, but to the calculation as a whole.

doc/syntax/index.qmd

@@ -7,6 +7,7 @@ ggsql augments the standard SQL syntax with a number of new clauses to describe
 
 - [`VISUALISE`](clause/visualise.qmd) initiates the visualisation part of the query
 - [`DRAW`](clause/draw.qmd) adds a new layer to the visualisation
+    - [`PLACE`](clause/place.qmd) adds an annotation layer
 - [`SCALE`](clause/scale.qmd) specify how an aesthetic should be scaled
 - [`FACET`](clause/facet.qmd) describes how data should be split into small multiples
 - [`PROJECT`](clause/project.qmd) is used for selecting the coordinate system to use
@@ -25,12 +26,14 @@ There are many different layers to choose from when visualising your data. Some
 - [`area`](layer/type/area.qmd) is used to display series as an area chart.
 - [`ribbon`](layer/type/ribbon.qmd) is used to display series extrema.
 - [`polygon`](layer/type/polygon.qmd) is used to display arbitrary shapes as polygons.
+- [`text`](layer/text.qmd) is used to render datapoints as text.
 - [`bar`](layer/type/bar.qmd) creates a bar chart, optionally calculating y from the number of records in each bar.
 - [`density`](layer/type/density.qmd) creates univariate kernel density estimates, showing the distribution of a variable.
 - [`violin`](layer/type/violin.qmd) displays a rotated kernel density estimate.
 - [`histogram`](layer/type/histogram.qmd) bins the data along the x axis and produces a bar for each bin showing the number of records in it.
 - [`boxplot`](layer/type/boxplot.qmd) displays continuous variables as 5-number summaries.
 - [`errorbar`](layer/type/errorbar.qmd) a line segment with hinges at the endpoints.
+- [`smooth`](layer/type/smooth.qmd) a trendline that follows the data shape.
 
 ### Position adjustments
 - [`stack`](layer/position/stack.qmd) places objects with a shared baseline on top of each other.

doc/syntax/layer/type/linear.qmd

@@ -46,10 +46,10 @@ Add a simple reference line to a scatterplot:
 ```{ggsql}
 VISUALISE FROM ggsql:penguins
   DRAW point MAPPING bill_len AS x, bill_dep AS y
-  DRAW linear MAPPING 0.4 AS coef, -1 AS intercept
+  PLACE linear SETTING coef => 0.4, intercept => -1
 ```
 
-Add multiple reference lines with different colors from a separate dataset:
+Add multiple reference lines with different colors from a separate dataset. Note we're mapping from data here, so we use `DRAW` instead of `PLACE`.
 
 ```{ggsql}
 WITH lines AS (