@fundar/data-chart-telling 0.0.64 → 1.1.0

package/examples/data.ts

@@ -0,0 +1,324 @@
+// Small real datasets shared by the examples and the documentation figures.
+// Each section names its source; values are rounded to one decimal.
+
+// ── Monthly inflation by region ─────────────────────────────────────────────
+// INDEC, consumer price index (IPC, base December 2016), via the datos.gob.ar
+// series API. Change from the previous month, in percent, January 2023 to
+// August 2026.
+
+export type RegionRow = { date: Date; region: string; value: number };
+
+export const MONTHS = Array.from(
+	{ length: 44 },
+	(_, monthIndex) => new Date(Date.UTC(2023, monthIndex, 1))
+);
+
+const INFLATION_BY_REGION = [
+	{
+		region: 'GBA',
+		inflation: [
+			6, 6.7, 7.8, 8.6, 8, 5.8, 6.2, 12.3, 12.2, 8.6, 12.9, 25.1, 19.6, 15, 11.5, 9.2, 4.3, 4.4, 4,
+			4.1, 3.7, 2.8, 2.6, 2.9, 2, 2.2, 3.9, 2.8, 1.5, 2, 1.9, 1.9, 2.1, 2.4, 2.5, 2.8, 2.8, 2.6,
+			3.4, 2.8, 2.3, 1.9, 2.3, 1.6
+		]
+	},
+	{
+		region: 'Cuyo',
+		inflation: [
+			6.4, 6.7, 7.9, 7.2, 7.5, 5.3, 6.3, 12.3, 13.7, 7.4, 12.8, 25.8, 22.3, 13.5, 9.3, 8.1, 4.3,
+			5.1, 4.6, 4.5, 3, 2.2, 2.1, 2.3, 2, 2.7, 3.5, 2.9, 1.6, 1, 1.9, 2.1, 2.2, 2.3, 2.8, 3, 3, 3.4,
+			3.2, 2.1, 2.1, 1.6, 1.9, 1.7
+		]
+	},
+	{
+		region: 'Northwest',
+		inflation: [
+			6.3, 7.3, 7.3, 7.7, 8, 6.6, 6.1, 13.7, 13.2, 7.7, 11.8, 25.2, 21.7, 11.7, 8.8, 9.1, 4.2, 4.8,
+			3.6, 5, 3.4, 2.6, 1.9, 2.7, 2.6, 2.6, 4.3, 2.9, 1.2, 1.2, 1.7, 2, 2.2, 2.1, 2.3, 2.6, 2.8,
+			3.5, 4, 2.5, 2.1, 1.7, 2, 1.8
+		]
+	}
+];
+
+export const REGIONS = INFLATION_BY_REGION.map(({ region }) => region);
+
+export const REGION_VALUES: RegionRow[] = INFLATION_BY_REGION.flatMap(({ region, inflation }) =>
+	MONTHS.map((date, monthIndex) => ({ date, region, value: inflation[monthIndex] }))
+);
+
+// ── International commodity prices ──────────────────────────────────────────
+// IMF, Primary Commodity Prices (PCPS), via DBnomics. Monthly, 2021-2024, as
+// an index with January 2021 = 100 so every commodity shares one axis.
+
+export type PriceRow = { date: Date; commodity: string; index: number };
+
+const PRICE_INDEX_BY_COMMODITY = [
+	{
+		commodity: 'Brent oil',
+		index: [
+			100, 113, 119, 119, 124, 133, 135, 128, 135, 152, 146, 135, 155, 171, 204, 192, 203, 213, 191,
+			177, 164, 170, 165, 148, 152, 151, 144, 151, 137, 136, 145, 154, 168, 161, 149, 140, 143, 148,
+			154, 161, 150, 150, 152, 143, 132, 136, 133, 133
+		]
+	},
+	{
+		commodity: 'Natural gas',
+		index: [
+			100, 110, 99, 101, 112, 124, 144, 152, 192, 210, 193, 146, 160, 169, 188, 255, 308, 286, 268,
+			331, 296, 230, 245, 217, 131, 92, 91, 83, 87, 94, 100, 100, 102, 120, 115, 96, 103, 68, 66,
+			67, 91, 106, 84, 79, 91, 97, 113, 130
+		]
+	},
+	{
+		commodity: 'Coal',
+		index: [
+			100, 102, 105, 108, 115, 145, 168, 191, 207, 265, 195, 199, 255, 299, 388, 368, 460, 470, 477,
+			492, 514, 469, 405, 470, 445, 268, 215, 221, 197, 152, 155, 168, 185, 166, 145, 164, 155, 141,
+			151, 151, 163, 158, 156, 167, 163, 168, 165, 154
+		]
+	},
+	{
+		commodity: 'Wheat',
+		index: [
+			100, 101, 97, 101, 117, 100, 102, 116, 113, 124, 133, 136, 137, 146, 163, 171, 187, 167, 135,
+			136, 146, 149, 145, 136, 135, 140, 130, 131, 126, 119, 117, 101, 96, 91, 91, 97, 95, 92, 89,
+			88, 96, 86, 77, 74, 79, 83, 78, 78
+		]
+	}
+];
+
+export const PRICES: PriceRow[] = PRICE_INDEX_BY_COMMODITY.flatMap(({ commodity, index }) =>
+	index.map((value, monthIndex) => ({
+		date: new Date(Date.UTC(2021, monthIndex, 1)),
+		commodity,
+		index: value
+	}))
+);
+
+// ── Life expectancy at birth in Argentina, by sex ───────────────────────────
+// INDEC, life tables. Each year stands for the period around it (1947 is
+// 1946-1948, 2001 is 2000-2001, ...).
+
+export type LifeRow = { year: number; sex: string; value: number | null };
+
+const LIFE_EXPECTANCY = [
+	{ year: 1947, female: 61.4, male: 56.9 },
+	{ year: 1965, female: 69.5, male: 63.3 },
+	{ year: 1972, female: 70.8, male: 64.1 },
+	{ year: 1980, female: 72.7, male: 65.5 },
+	{ year: 1991, female: 75.6, male: 68.4 },
+	{ year: 2001, female: 77.5, male: 70 },
+	{ year: 2009, female: 78.8, male: 72.1 },
+	{ year: 2019, female: 80.2, male: 74.4 }
+];
+
+export const LIFE: LifeRow[] = LIFE_EXPECTANCY.flatMap(({ year, female, male }) => [
+	{ year, sex: 'female', value: female },
+	{ year, sex: 'male', value: male }
+]);
+
+/** The female series with holes: the first year, one in the middle and the last. */
+export const LIFE_GAPS: LifeRow[] = LIFE.filter((row) => row.sex === 'female').map((row) =>
+	[1947, 1980, 2019].includes(row.year) ? { ...row, value: null } : row
+);
+
+// ── Life expectancy at birth by province, 2019 ──────────────────────────────
+// Same source as above.
+
+export type ProvinceRow = { province: string; sex: string; value: number };
+
+const LIFE_EXPECTANCY_BY_PROVINCE = [
+	{ province: 'Buenos Aires', female: 79.9, male: 74.1 },
+	{ province: 'Córdoba', female: 80.8, male: 75.2 },
+	{ province: 'Mendoza', female: 81, male: 75.3 },
+	{ province: 'Salta', female: 79.5, male: 74 },
+	{ province: 'Chubut', female: 82.1, male: 74.9 }
+];
+
+export const PROVINCES = LIFE_EXPECTANCY_BY_PROVINCE.map(({ province }) => province);
+
+export const PROVINCE_VALUES: ProvinceRow[] = LIFE_EXPECTANCY_BY_PROVINCE.flatMap(
+	({ province, female, male }) => [
+		{ province, sex: 'female', value: female },
+		{ province, sex: 'male', value: male }
+	]
+);
+
+// ── Population of Buenos Aires City by age and sex ──────────────────────────
+// National censuses 1991-2022. Share of the city's population, in percent.
+
+/** The 2022 census: one row per age group and sex, for a pyramid. */
+export type AgeRow = { ageGroup: string; sex: string; share: number };
+
+const POPULATION_BY_AGE = [
+	{ ageGroup: '0-4', female: 2.3, male: 2.4 },
+	{ ageGroup: '5-9', female: 3.1, male: 3.2 },
+	{ ageGroup: '10-14', female: 3.1, male: 3.2 },
+	{ ageGroup: '15-19', female: 3, male: 3.1 },
+	{ ageGroup: '20-24', female: 3.5, male: 3.3 },
+	{ ageGroup: '25-29', female: 4, male: 3.7 },
+	{ ageGroup: '30-34', female: 3.8, male: 3.6 },
+	{ ageGroup: '35-39', female: 3.7, male: 3.5 },
+	{ ageGroup: '40-44', female: 3.4, male: 3.1 },
+	{ ageGroup: '45-49', female: 3.3, male: 2.8 },
+	{ ageGroup: '50-54', female: 3.1, male: 2.5 },
+	{ ageGroup: '55-59', female: 2.9, male: 2.4 },
+	{ ageGroup: '60-64', female: 2.8, male: 2.2 },
+	{ ageGroup: '65-69', female: 2.6, male: 2 },
+	{ ageGroup: '70-74', female: 2.6, male: 1.8 },
+	{ ageGroup: '75-79', female: 2.3, male: 1.4 },
+	{ ageGroup: '80-84', female: 1.8, male: 0.9 },
+	{ ageGroup: '85+', female: 2.5, male: 0.9 }
+];
+
+export const AGE_GROUPS = POPULATION_BY_AGE.map(({ ageGroup }) => ageGroup);
+
+export const AGES: AgeRow[] = POPULATION_BY_AGE.flatMap(({ ageGroup, female, male }) => [
+	{ ageGroup, sex: 'Female', share: female },
+	{ ageGroup, sex: 'Male', share: male }
+]);
+
+/** The same census data over the years, grouped by sex: the share of each broad age group. */
+export type AgeShareRow = { year: number; ageGroup: string; share: number };
+
+export const AGE_SHARES: AgeShareRow[] = [
+	{ year: 1991, ageGroup: '0-14', share: 19 },
+	{ year: 1991, ageGroup: '15-29', share: 21.7 },
+	{ year: 1991, ageGroup: '30-44', share: 20.1 },
+	{ year: 1991, ageGroup: '45-64', share: 22.8 },
+	{ year: 1991, ageGroup: '65+', share: 16.5 },
+	{ year: 2001, ageGroup: '0-14', share: 16.9 },
+	{ year: 2001, ageGroup: '15-29', share: 23.2 },
+	{ year: 2001, ageGroup: '30-44', share: 19.9 },
+	{ year: 2001, ageGroup: '45-64', share: 22.3 },
+	{ year: 2001, ageGroup: '65+', share: 17.2 },
+	{ year: 2010, ageGroup: '0-14', share: 16.4 },
+	{ year: 2010, ageGroup: '15-29', share: 22.4 },
+	{ year: 2010, ageGroup: '30-44', share: 22.2 },
+	{ year: 2010, ageGroup: '45-64', share: 22.9 },
+	{ year: 2010, ageGroup: '65+', share: 16.3 },
+	{ year: 2022, ageGroup: '0-14', share: 17.4 },
+	{ year: 2022, ageGroup: '15-29', share: 20.7 },
+	{ year: 2022, ageGroup: '30-44', share: 21.1 },
+	{ year: 2022, ageGroup: '45-64', share: 22 },
+	{ year: 2022, ageGroup: '65+', share: 18.9 }
+];
+
+/** The same census data over the years, grouped by age: the share of each sex. */
+export type SexShareRow = { year: number; sex: string; share: number };
+
+export const SEX_SHARES: SexShareRow[] = [
+	{ year: 1991, sex: 'Female', share: 54.6 },
+	{ year: 1991, sex: 'Male', share: 45.5 },
+	{ year: 2001, sex: 'Female', share: 54.2 },
+	{ year: 2001, sex: 'Male', share: 45.3 },
+	{ year: 2010, sex: 'Female', share: 54.2 },
+	{ year: 2010, sex: 'Male', share: 46 },
+	{ year: 2022, sex: 'Female', share: 53.8 },
+	{ year: 2022, sex: 'Male', share: 46.2 }
+];
+
+// ── Countries, 2007 ─────────────────────────────────────────────────────────
+// Gapminder, via plotly/datasets. GDP per capita in US dollars (PPP, 2005
+// prices), life expectancy in years, population in millions. `income` groups
+// the countries by GDP per capita.
+
+export type CountryRow = {
+	country: string;
+	gdp: number;
+	life: number;
+	population: number;
+	continent: string;
+	income: string;
+};
+
+const COUNTRY_INDICATORS = [
+	{ country: 'Nigeria', continent: 'Africa', gdp: 2014, life: 46.9, population: 135 },
+	{ country: 'Egypt', continent: 'Africa', gdp: 5581, life: 71.3, population: 80.3 },
+	{ country: 'South Africa', continent: 'Africa', gdp: 9270, life: 49.3, population: 44 },
+	{ country: 'Ethiopia', continent: 'Africa', gdp: 691, life: 52.9, population: 76.5 },
+	{ country: 'Kenya', continent: 'Africa', gdp: 1463, life: 54.1, population: 35.6 },
+	{ country: 'Morocco', continent: 'Africa', gdp: 3820, life: 71.2, population: 33.8 },
+	{ country: 'Ghana', continent: 'Africa', gdp: 1328, life: 60, population: 22.9 },
+	{ country: 'Argentina', continent: 'Americas', gdp: 12779, life: 75.3, population: 40.3 },
+	{ country: 'Brazil', continent: 'Americas', gdp: 9066, life: 72.4, population: 190 },
+	{ country: 'Chile', continent: 'Americas', gdp: 13172, life: 78.6, population: 16.3 },
+	{ country: 'Mexico', continent: 'Americas', gdp: 11978, life: 76.2, population: 108.7 },
+	{ country: 'United States', continent: 'Americas', gdp: 42952, life: 78.2, population: 301.1 },
+	{ country: 'Canada', continent: 'Americas', gdp: 36319, life: 80.7, population: 33.4 },
+	{ country: 'Bolivia', continent: 'Americas', gdp: 3822, life: 65.6, population: 9.1 },
+	{ country: 'China', continent: 'Asia', gdp: 4959, life: 73, population: 1318.7 },
+	{ country: 'India', continent: 'Asia', gdp: 2452, life: 64.7, population: 1110.4 },
+	{ country: 'Japan', continent: 'Asia', gdp: 31656, life: 82.6, population: 127.5 },
+	{ country: 'Indonesia', continent: 'Asia', gdp: 3541, life: 70.7, population: 223.5 },
+	{ country: 'Vietnam', continent: 'Asia', gdp: 2442, life: 74.2, population: 85.3 },
+	{ country: 'Pakistan', continent: 'Asia', gdp: 2606, life: 65.5, population: 169.3 },
+	{ country: 'South Korea', continent: 'Asia', gdp: 23348, life: 78.6, population: 49 },
+	{ country: 'Germany', continent: 'Europe', gdp: 32170, life: 79.4, population: 82.4 },
+	{ country: 'France', continent: 'Europe', gdp: 30470, life: 80.7, population: 61.1 },
+	{ country: 'Spain', continent: 'Europe', gdp: 28821, life: 80.9, population: 40.4 },
+	{ country: 'Italy', continent: 'Europe', gdp: 28570, life: 80.5, population: 58.1 },
+	{ country: 'United Kingdom', continent: 'Europe', gdp: 33203, life: 79.4, population: 60.8 },
+	{ country: 'Poland', continent: 'Europe', gdp: 15390, life: 75.6, population: 38.5 },
+	{ country: 'Norway', continent: 'Europe', gdp: 49357, life: 80.2, population: 4.6 }
+];
+
+export const COUNTRIES: CountryRow[] = COUNTRY_INDICATORS.map((country) => ({
+	...country,
+	income: country.gdp >= 20000 ? 'High' : country.gdp >= 5000 ? 'Middle' : 'Low'
+}));
+
+// ── Households of Buenos Aires City by rooms and people, 2022 ───────────────
+// 2022 national census. Share of all households, in percent.
+
+export type HouseholdRow = { rooms: string; people: string; share: number };
+
+export const ROOMS = ['1', '2', '3', '4', '5+'];
+
+const HOUSEHOLD_SHARES = [
+	{ people: '1', byRooms: [8.8, 14.8, 9.6, 3.7, 2.1] },
+	{ people: '2', byRooms: [3, 8.4, 9.3, 4.5, 2.9] },
+	{ people: '3', byRooms: [1.2, 3.4, 5.9, 3.2, 2] },
+	{ people: '4', byRooms: [0.6, 1.8, 3.8, 3, 2] },
+	{ people: '5+', byRooms: [0.3, 1, 1.7, 1.5, 1.6] }
+];
+
+export const HOUSEHOLDS: HouseholdRow[] = HOUSEHOLD_SHARES.flatMap(({ people, byRooms }) =>
+	ROOMS.map((rooms, roomsIndex) => ({ rooms, people, share: byRooms[roomsIndex] }))
+);
+
+// ── Adult heights by sex ────────────────────────────────────────────────────
+// Nancy Howell's census of the !Kung San (Howell1, from the rethinking R
+// package), adults only. Heights in centimeters, sorted.
+
+export type HeightRow = { height: number; group: string };
+
+const FEMALE_HEIGHTS = [
+	137, 137, 138, 139, 140, 140, 140, 141, 142, 142, 142, 142, 142, 142, 143, 143, 143, 143, 143,
+	143, 143, 143, 144, 144, 144, 144, 144, 144, 144, 144, 144, 144, 145, 145, 145, 145, 145, 145,
+	145, 145, 145, 145, 145, 145, 145, 145, 146, 146, 146, 146, 146, 146, 146, 146, 147, 147, 147,
+	147, 147, 147, 147, 147, 147, 147, 147, 147, 147, 147, 148, 148, 148, 148, 148, 148, 148, 148,
+	148, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 149, 150, 150,
+	150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 150, 151,
+	151, 151, 151, 151, 152, 152, 152, 152, 152, 152, 152, 152, 152, 152, 152, 152, 152, 152, 152,
+	152, 152, 152, 153, 153, 153, 153, 153, 153, 154, 154, 154, 154, 154, 154, 154, 154, 154, 154,
+	154, 154, 154, 154, 155, 155, 155, 155, 155, 155, 155, 156, 156, 156, 156, 156, 156, 156, 156,
+	156, 156, 156, 156, 157, 157, 157, 157, 157, 158, 159, 159, 160, 162, 163, 163
+];
+
+const MALE_HEIGHTS = [
+	140, 142, 146, 147, 148, 149, 149, 149, 149, 151, 151, 152, 152, 152, 152, 152, 152, 152, 152,
+	153, 154, 154, 154, 155, 155, 155, 155, 155, 155, 155, 156, 156, 156, 156, 157, 157, 157, 157,
+	157, 157, 157, 157, 157, 157, 157, 157, 157, 158, 158, 158, 158, 158, 158, 158, 159, 159, 159,
+	159, 159, 159, 159, 159, 159, 159, 159, 159, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160,
+	160, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161,
+	161, 161, 161, 161, 161, 162, 162, 162, 162, 162, 162, 162, 163, 163, 163, 163, 163, 163, 163,
+	163, 163, 163, 163, 163, 163, 163, 164, 164, 164, 164, 164, 164, 164, 164, 164, 164, 164, 165,
+	165, 166, 166, 166, 166, 166, 166, 166, 166, 167, 167, 167, 167, 167, 167, 168, 168, 168, 169,
+	169, 169, 170, 170, 170, 170, 171, 171, 171, 171, 173, 173, 179
+];
+
+export const HEIGHTS: HeightRow[] = [
+	...FEMALE_HEIGHTS.map((height) => ({ height, group: 'female' })),
+	...MALE_HEIGHTS.map((height) => ({ height, group: 'male' }))
+];

package/llms-full.txt

@@ -0,0 +1,142 @@
+# @fundar/data-chart-telling - guide for LLMs and coding agents
+
+Svelte 5 plot components on top of svelteplot. This file is checked against the source; the runnable files in `examples/` are type-checked and mounted by the test suite, and `docs/` has one page per topic. If this text and `dist/**/*.d.ts` differ, the types are right - tell the user.
+
+## Setup
+
+- Peer dependencies: `svelte@^5`, `svelteplot@^0.14`; `topojson-client` only for GeoPlot with TopoJSON.
+- The package ships Svelte components, so the app builds with `@sveltejs/vite-plugin-svelte` or SvelteKit.
+- Import from the package root: `import { LinePlot } from '@fundar/data-chart-telling'`.
+- Types ship with the package (`dist/index.d.ts`, JSDoc on every config field).
+
+## The mental model
+
+- A **plot** is one graph (axes + marks). Titles, subtitle, caption, legend, facets and a timeline are props of the plot itself.
+- Plots: `LinePlot AreaPlot BarPlot HistogramPlot BoxPlot HeatmapPlot PyramidPlot ScatterPlot GeoPlot`.
+- `PlotComposer` lays several plots out in one figure with shared hover, legend and timeline.
+- `width` and `height` are pixel numbers on a standalone plot. To fill a container or the window, bind its size (`examples/ResponsiveLine.svelte`) and render the plot once both are > 0.
+
+## Data
+
+Two ways to give data, one per plot:
+
+```svelte
+<LinePlot data={rows} x="year" y="value" color="region" {width} {height} />
+<LinePlot series={[{ name: 'North', x: 'year', y: 'value', data: rowsNorth }]} {width} {height} />
+```
+
+- `x`, `y`, `color`, `grouping`, `opacity`, `symbol`, `r`, `length` take a field name or an accessor function.
+- `grouping` splits `data` into series. When unset, `color` groups too, so the usual call is `color="region"`: one series per region, each with its own color.
+- Dates are `Date` objects (UTC midnight avoids timezone shifts); numeric years are numbers.
+- Rows are parsed, typed and sorted by the app before they reach the plot (a `?raw` CSV import plus a small parser is enough).
+- A series' name is what the legend, value labels and tooltip show: name values in the data.
+
+## Props of every x/y plot
+
+| Prop | Purpose |
+| --- | --- |
+| `title` `subtitle` `caption` | Text chrome. `header` / `footer` snippets replace title+subtitle / caption. |
+| `legend` | unset/`true`: automatic legend; `false`: none; `{ series: { interactive: { enabled: true, disabled: { mode: 'omit' } } } }` adjusts a section. |
+| `order` | Chrome blocks top to bottom, e.g. `['title','subtitle','legend','plot','caption']`; rows as `'(plot, timeline)'`; `'divider'` between blocks. |
+| `scales` | Per channel: `{ x: { label, tickFormat, domain, type, ticks, grid, niceTolerance, edgeTicks }, y: {...}, color: { scheme, domain } }`. Stacked parts adding up to a hair past a tick (`100.2`) stay on it; `niceTolerance` (default `0.05` of a step) tunes that. A continuous x axis also ticks the data's first and last values (y too with `edgeTicks: true`); `edgeTicks: false` or `{ collision: 'drop-nice'\|'drop-edge'\|'extend' }` (global defaults: `axis.edgeTicks.x` / `.y`). |
+| `styles` | `{ values: {...}, frame: true, gaps: {...} }` (shape depends on the kind). |
+| `segments` | Style ranges of the data (rule 1 below). |
+| `markers` | Extra marks, an array of `{ type: '...', ... }`. |
+| `margins` | `{ top, right, bottom, left }`, each a number or `'auto'` (all `'auto'` by default). |
+| `tooltip` | `true` or `{ strategy, sync, format, content, series, anchorX, anchorY }`. The text lists matched rows highest value first; a `content` snippet gets them unsorted. |
+| `timeline` | `{ accessor: 'year' }` steps through the rows by a field, drawn as a player bar (default); `type: 'rule'` draws a rule beside the plot instead. The field may hold numbers, `Date`s or date strings (ISO, or any other with `dateFormat: 'DD/MM/YYYY'`); date steps read as dates, and reach `onvalue`, `player.format` and `useFigure().timeline` (`steps`, `value`, `seekValue`) as `Date`s. |
+| `facet` | `{ by: 'field', columns, gap, scales: 'shared'\|'free', mode: 'grid'\|'carousel'\|'paginated' }` or `{ rows, cols }`. |
+| `transforms` `statistics` | svelteplot transforms / derived summaries (regression, movingAverage, ...). |
+
+Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `PyramidPlot` mirrors two series around zero; `HeatmapPlot` colors cells by `color`; `HistogramPlot` bins one numeric field; `BoxPlot` x = category, y = value, one box per category (its tooltip row is the box summary: `min`, `p25`, `median`, `p75`, `max`, `count`, `outliers`); `ScatterPlot` takes `r` (size) and `symbol`; `GeoPlot` takes GeoJSON/TopoJSON in `data` and `coordinates` for the projection (`docs/geo.md`).
+
+## Switches
+
+- **Hover and tooltip** are enabled by `tooltip` and/or a hover marker. The usual look: `tooltip={true} markers={[{ type: 'hover' }]}`. `tooltip.strategy` is `'x' | 'y' | 'punctual' | 'series'`.
+- **Value labels**: `styles={{ values: { show: true } }}`. On a LinePlot they sit at the end of each series, spread apart automatically, and the right margin grows to fit them (keep `margins.right` at `'auto'`). Format with `values.format: (value, seriesName) => string`; style with `values.fontStyle`.
+- **Toggling series from the legend**: `interactive.enabled` on the series section.
+- **A frame** around the plot area: `styles={{ frame: true }}`.
+
+## Rules that matter
+
+1. `segments` is an object keyed by series name or `'default'`: `{ default: [{ areas: [{ x: { from, to } }], styles: { stroke: { strokeDasharray: '6 4' } } }] }`. A segment without `areas` is a baseline for everything; area-specific segments override it.
+2. The global configuration holds data (`setConfiguration(...)` is cloned); functions go in plot props such as `format` and `tickFormat`.
+3. A continuous color ramp is `scales.color.scheme: [colorA, colorB]` (or a named ramp such as `'blues'`); categorical colors come from `palette` or a `scheme` record.
+4. `margins` at `'auto'` (the default) fit value labels and long tick text from the measured text, also when `scales.y.domain` is pinned. A fixed number sets the side exactly.
+5. `tooltip.sync: true` in a `facet` or `PlotComposer` shows the highlight in every panel: that is how panels compare the same x.
+6. On a BarPlot the tooltip triggers anywhere over a bar's whole band (and its series' slice, when grouped).
+7. `r` takes raw values and its sqrt scale makes area follow the value; tune with `scales.r.range`. A literal number is a fixed pixel radius.
+8. Narrow plots with long category or series names: shorten the text in the data, format with `tickFormat` / `values.format`, or give `margins` more room.
+9. In Svelte 5 components, `state` is taken by the `$state` rune: name local variables otherwise.
+10. Stacking is `transforms={[{ type: 'stackY' }]}`, also for horizontal bars (the value channel is the one stacked).
+
+## Reading and driving plot state (custom UI)
+
+Inside a plot's snippets (`header`, `footer`, tooltip `content`) or any child of a figure, call during component init:
+
+- `useFigure()` returns `{ hover, legend, timeline }` for the whole figure.
+- `usePlot()` returns the same plus `margins`, `scales`, `axes`, `data`, `width`, `height`, `svelteplot` (inside a plot, e.g. a `component` marker).
+- `legend.off` (names of hidden series), `legend.isOff(name)`, `legend.toggle(name, action)`, `turnOff`, `turnOn`. `action` is `{ mode: 'dim' | 'hide' | 'omit' }`; `'omit'` removes the series and refits the axes, so the visible domain follows `legend.off`.
+- `timeline.steps`, `value`, `progress`, `playing`, `seek(p)`, `seekValue(v)`, `next()`, `previous()`, `play()`, `pause()`, `toggle()`, `setSpeed()`.
+- `hover.activeX`, `activeY`, `activeSeries`, `source`.
+
+The timeline is a player bar by default: `timeline={{ accessor: 'year', player: { controls: ['play','value','slider','speed','loop'], format, autoplay, loop, speed, stepDuration } }}`. `type: 'rule'` draws a guide beside the plot instead, driven by `progress` (a slider or scroll position of your own).
+
+## Markers
+
+Add with `markers={[{ type: '...' }]}`. For x/y plots:
+`area arrow bar bollinger box brush cell component delaunayLink delaunayMesh delta density difference dot hover hull image line raster rect regression rule text tick trail voronoi voronoiMesh waffle`.
+GeoPlot: `graticule sphere dot text vector link contour inset geo-hover geo-component`.
+
+- `delta` annotates the difference between two series at a position: `{ type: 'delta', axis: 'x', at: 2020, from: { type: 'series', series: 'A' }, to: { type: 'series', series: 'B' }, formatDiff: (d) => d.toFixed(1) }`.
+- `rule` (`axis`, `value`), `text` (`text`), `dot` annotate; `component` mounts your own Svelte component inside the plot (it can call `usePlot()`).
+- Each plot kind types its own marker union (`AxisBasedMarkersConfig`, `GeoMarkersConfig`); `satisfies` on a markers array gives completion.
+
+## Theming and locale
+
+- `setConfiguration(partial)` deep-merges global defaults (colors, fonts, spacing, legend, tooltip, timeline); `resetConfiguration()` restores them. Inside an `$effect`, wrap the call in `untrack`.
+- `THEMES` has `Default Editorial Dark Compact`: `setConfiguration(THEMES.Editorial)`.
+- Number and date text follows `axis.locale` (default `'es-AR'`) in the configuration; per axis, `tickFormat: (d) => new Intl.NumberFormat('en-US').format(d)` or an `Intl.*FormatOptions` object.
+
+## Docs (in `docs/`)
+
+`getting-started.md`, `concepts.md`, `plots.md`, `scales.md`, `styles-and-segments.md`, `markers.md`, `transforms-and-statistics.md`, `tooltip-and-hover.md`, `legend.md`, `timeline.md`, `chrome.md`, `facets.md`, `composer.md`, `state.md`, `geo.md`, `theming.md`.
+
+## Examples (in `examples/`, all runnable)
+
+- `LineByRegion.svelte` - one line per region with title, legend, end labels and tooltip.
+- `ResponsiveLine.svelte` - fill the window, end-of-line labels, axis labels.
+- `Tooltip.svelte` - tooltip + hover marker.
+- `Segments.svelte` - styling a range of the data.
+- `LegendToggle.svelte` + `LegendReader.svelte` - interactive legend and reading its state.
+- `TimelinePlayer.svelte` - animated bar chart with a player.
+- `TimelineRule.svelte` - a timeline rule moved by a slider through `progress`.
+- `Facets.svelte` - small multiples with a synced tooltip.
+- `BarValues.svelte` - value labels on bars.
+- `CustomTooltip.svelte` + `TooltipCard.svelte` - a tooltip drawn with your own card (`tooltip.content`).
+- `FirstPlot.svelte` - the smallest plot: rows, fields and a pixel size.
+- `LineDates.svelte` - line per series over a date axis, with end labels.
+- `StackedArea.svelte` - stacked area plot.
+- `GroupedBars.svelte` - vertical bars grouped by color.
+- `HorizontalBars.svelte` - horizontal bars.
+- `Histogram.svelte` - overlapping histograms.
+- `Box.svelte` - box plots per group.
+- `Heatmap.svelte` - heatmap.
+- `Pyramid.svelte` - population pyramid.
+- `Scatter.svelte` - scatter plot sized, colored and shaped by channels.
+- `Scales.svelte` - axis labels, fixed domain, gridlines and series colors.
+- `ValueLabels.svelte` - end-of-line value labels with a custom format.
+- `Gaps.svelte` - filling gaps of missing values.
+- `SegmentHighlight.svelte` - highlighting a range of one series.
+- `SegmentsBySeries.svelte` - segments per series and shared rules.
+- `HeatmapSegments.svelte` - segments on a heatmap.
+- `Markers.svelte` - hover, rule and delta markers.
+- `StackedBars.svelte` - bars stacked with stackY.
+- `MovingAverage.svelte` - moving average with windowY.
+- `Regression.svelte` - linear regression with a confidence band.
+- `LegendSections.svelte` - explicit legend sections.
+- `Chrome.svelte` - title, subtitle and caption.
+- `ChromeOrder.svelte` - ordering chrome blocks with dividers.
+- `FacetsCarousel.svelte` - facets as a carousel.
+- `FacetsRowsCols.svelte` - facets by rows and columns.
+- `Composer.svelte` - several plots in one figure.

package/llms.txt

@@ -0,0 +1,77 @@
+# @fundar/data-chart-telling
+
+> Svelte 5 plot components (line, area, bar, histogram, box, heatmap, pyramid, scatter, geo) built on svelteplot, with titles, legends, tooltips, facets, timelines and value labels built in. Plots take pixel `width`/`height`; hover and tooltips are switched on with `tooltip` and a `hover` marker.
+
+Start with the full guide: it lists the mental model, the props every plot shares, the switches and the rules that matter. Runnable examples are type-checked, so copy them as a starting point.
+
+## Guide
+
+- [Full guide](./llms-full.txt): API overview, switches, rules, state hooks (`useFigure`, `usePlot`), markers, theming
+
+## Docs
+
+- [Getting started](./docs/getting-started.md): install, first plot, sizing, data
+- [Concepts](./docs/concepts.md): plots, figures, rows and series, channels, shared props
+- [Plots](./docs/plots.md): the nine plot kinds
+- [Scales](./docs/scales.md): axes and channel scales
+- [Styles and segments](./docs/styles-and-segments.md): value labels, frame, gaps, ranges of data
+- [Markers](./docs/markers.md): annotations, regions, hover highlight, custom components
+- [Transforms and statistics](./docs/transforms-and-statistics.md): stacking, binning, smoothing, regression
+- [Tooltip and hover](./docs/tooltip-and-hover.md): tooltip options, hover marker, sync
+- [Legend](./docs/legend.md): automatic legend, toggling series, sections
+- [Timeline](./docs/timeline.md): player (default) and rule
+- [Chrome](./docs/chrome.md): title, caption, header, footer, order, dividers
+- [Facets](./docs/facets.md): small multiples
+- [Composer](./docs/composer.md): several plots in one figure
+- [Reading plot state](./docs/state.md): `useFigure`, `usePlot`
+- [Maps](./docs/geo.md): GeoPlot, projections, camera, map markers
+- [Theming](./docs/theming.md): configuration, themes, locale, CSS variables
+
+## Examples
+
+- [Line plot by region with title, legend, end labels and tooltip](./examples/LineByRegion.svelte)
+- [Responsive line chart with end labels](./examples/ResponsiveLine.svelte)
+- [Tooltip and hover marker](./examples/Tooltip.svelte)
+- [Segments (styling a range of data)](./examples/Segments.svelte)
+- [Interactive legend and reading its state](./examples/LegendToggle.svelte)
+- [Timeline player](./examples/TimelinePlayer.svelte)
+- [Timeline rule driven by a slider](./examples/TimelineRule.svelte)
+- [Facets with a synced tooltip](./examples/Facets.svelte)
+- [Bars with value labels](./examples/BarValues.svelte)
+- [Custom tooltip card](./examples/CustomTooltip.svelte)
+- [The smallest plot: rows, fields and a pixel size](./examples/FirstPlot.svelte)
+- [Line per series over a date axis, with end labels](./examples/LineDates.svelte)
+- [Stacked area plot](./examples/StackedArea.svelte)
+- [Vertical bars grouped by color](./examples/GroupedBars.svelte)
+- [Horizontal bars](./examples/HorizontalBars.svelte)
+- [Overlapping histograms](./examples/Histogram.svelte)
+- [Box plots per group](./examples/Box.svelte)
+- [Heatmap](./examples/Heatmap.svelte)
+- [Population pyramid](./examples/Pyramid.svelte)
+- [Scatter plot sized, colored and shaped by channels](./examples/Scatter.svelte)
+- [Axis labels, fixed domain, gridlines and series colors](./examples/Scales.svelte)
+- [End-of-line value labels with a custom format](./examples/ValueLabels.svelte)
+- [Filling gaps of missing values](./examples/Gaps.svelte)
+- [Highlighting a range of one series](./examples/SegmentHighlight.svelte)
+- [Segments per series and shared rules](./examples/SegmentsBySeries.svelte)
+- [Segments on a heatmap](./examples/HeatmapSegments.svelte)
+- [Hover, rule and delta markers](./examples/Markers.svelte)
+- [Bars stacked with stackY](./examples/StackedBars.svelte)
+- [Moving average with windowY](./examples/MovingAverage.svelte)
+- [Linear regression with a confidence band](./examples/Regression.svelte)
+- [Explicit legend sections](./examples/LegendSections.svelte)
+- [Title, subtitle and caption](./examples/Chrome.svelte)
+- [Ordering chrome blocks with dividers](./examples/ChromeOrder.svelte)
+- [Facets as a carousel](./examples/FacetsCarousel.svelte)
+- [Facets by rows and columns](./examples/FacetsRowsCols.svelte)
+- [Several plots in one figure](./examples/Composer.svelte)
+- [Shared example data](./examples/data.ts)
+
+## Types
+
+- [Public exports](./dist/index.d.ts): every config type, with JSDoc on each field
+
+## Optional
+
+- [README](./README.md): overview and documentation index
+- [Package manifest](./package.json): peer dependencies (`svelte`, `svelteplot`, optional `topojson-client`)

package/package.json

@@ -1,9 +1,33 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "0.0.64",
+  "version": "1.1.0",
+  "description": "Declarative charts, maps and small multiples for Svelte, built on svelteplot.",
+  "license": "MIT",
+  "author": "Ezequiel Puerta",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/datos-Fundar/data-chart-telling.git"
+  },
+  "homepage": "https://github.com/datos-Fundar/data-chart-telling#readme",
+  "bugs": {
+    "url": "https://github.com/datos-Fundar/data-chart-telling/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
   "type": "module",
   "files": [
-    "dist"
+    "LICENSE",
+    "CHANGELOG.md",
+    "dist",
+    "docs",
+    "!docs/images",
+    "examples",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "sideEffects": [
     "**/*.css"
@@ -19,8 +43,10 @@
   },
   "dependencies": {
     "@types/geojson": "^7946.0.16",
+    "d3-array": "^3.2.4",
     "d3-geo": "^3.1.1",
     "d3-interpolate": "^3.0.1",
+    "d3-scale-chromatic": "^3.1.0",
     "d3-selection": "^3.0.0",
     "d3-zoom": "^3.0.0"
   },
@@ -45,8 +71,10 @@
     "@storybook/svelte-vite": "^10.4.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@types/d3-array": "^3.2.2",
     "@types/d3-geo": "^3.1.0",
     "@types/d3-interpolate": "^3.0.4",
+    "@types/d3-scale-chromatic": "^3.1.0",
     "@types/d3-selection": "^3.0.11",
     "@types/d3-zoom": "^3.0.8",
     "@types/node": "^22",
@@ -58,8 +86,9 @@
     "eslint-plugin-storybook": "^10.4.1",
     "eslint-plugin-svelte": "^3.17.0",
     "globals": "^17.4.0",
+    "husky": "^9.1.7",
     "knip": "^6.32.1",
-    "playwright": "^1.60.0",
+    "playwright": "^1.64.0",
     "prettier": "^3.8.1",
     "prettier-plugin-svelte": "^3.5.1",
     "publint": "^0.3.18",
@@ -75,7 +104,12 @@
     "vitest-browser-svelte": "^2.1.1"
   },
   "keywords": [
-    "svelte"
+    "svelte",
+    "svelteplot",
+    "charts",
+    "data-visualization",
+    "maps",
+    "small-multiples"
   ],
   "scripts": {
     "build": "svelte-package",
@@ -85,8 +119,11 @@
     "lint": "prettier --check . && eslint .",
     "format": "prettier --write .",
     "test": "vitest run --project=unit --project=browser",
+    "test:coverage": "node scripts/coverage.mjs",
     "test:stories": "vitest run --project=storybook",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "docs:images": "node scripts/docs-images.mjs",
+    "docs:examples": "node scripts/sync-examples.mjs"
   }
 }