@graphysdk/geom-waterfall 0.0.0-stage → 0.1.0

package/dist/renderer/waterfall.d.ts

@@ -0,0 +1,15 @@
+import { BoundGeomRendererDefinition } from '@graphysdk/react';
+import { WaterfallGeom } from '../engine/waterfall.geom';
+/**
+ * The waterfall plugin: pass it to `createGraphyKit({ plugins: [waterfall] })` for `kit.geom.waterfall()`.
+ *
+ * @example
+ *   const kit = createGraphyKit({ plugins: [waterfall] });
+ *   const spec = kit.pipe(
+ *     kit.createSpec({ x: 'item', y: 'amount' }),
+ *     kit.geom.waterfall({ aes: { measure: 'measure' } }),
+ *     kit.scale.x.discrete(),
+ *     kit.scale.y.continuous()
+ *   );
+ */
+export declare const waterfall: BoundGeomRendererDefinition<WaterfallGeom>;

package/dist/utils/read-waterfall.d.ts

@@ -0,0 +1,29 @@
+import { MainAxis, Observation, SceneLayer } from '@graphysdk/react';
+import { WaterfallKind } from './waterfall-columns';
+/** A bar placed by its band on the main axis and its interval on the other, each a `[0, 1]` fraction. */
+export interface Step {
+    observation: Observation;
+    /** The centre of the bar's band. */
+    band: number;
+    /** The bar's two edges on the main axis. */
+    bandStart: number;
+    bandEnd: number;
+    /** The bar's two ends on the value axis, lower first whichever way it runs. */
+    low: number;
+    high: number;
+    /** The running total the bar starts from: the previous bar's end for a step, zero for a total. */
+    start: number;
+    /** The running total the bar ends on, where the connector to the next bar runs. */
+    end: number;
+    kind: WaterfallKind;
+}
+/**
+ * Reads where a bar sits. The flip is already baked into the position columns, so under `coord.flip()` the
+ * band is `y`/`yMin`/`yMax` and the bar runs `xMin` to `xMax`; its start and end are scaled on the value axis whatever
+ * the flip. `null` for a step with no value, which draws nothing.
+ */
+export declare const readStep: (observation: Observation, mainAxis: MainAxis) => Step | null;
+/** Reads every bar of a layer in its data order, which is the order the total runs in. */
+export declare const readSteps: (observations: Iterable<Observation>, mainAxis: MainAxis) => Step[];
+/** The variable an explicit `group` maps, the only mapping that splits the running total. */
+export declare const readGroupVariable: (value: SceneLayer["mapping"]["group"]) => string | null;

package/dist/utils/waterfall-columns.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The columns `compile()` writes beside the position columns. Authors name them in a `highlight` or an entry's
+ * `where`, so they are part of the geom's API.
+ */
+export declare const WATERFALL_COLUMNS: {
+    /** The running total a bar starts from: the previous bar's end, or zero for a total. */
+    readonly start: "waterfallStart";
+    /** The running total a bar ends on, which the connector to the next bar carries on from. */
+    readonly end: "waterfallEnd";
+    /** Whether a bar is a step up, a step down or a total (see {@link WaterfallKind}). */
+    readonly kind: "waterfallKind";
+    /** The figure a bar shows: its change for a step, the running total for a total or an absolute bar. */
+    readonly value: "waterfallValue";
+};
+/**
+ * What a bar is, which is what colours it. Read from the values rather than the scaled positions, so a
+ * reversed value axis still paints an increase as an increase.
+ */
+export type WaterfallKind = 'increase' | 'decrease' | 'total';

package/dist/utils/waterfall-params.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where a connector runs from one bar to the next, in Plotly's vocabulary: across the gap between them, or
+ * across both bars' bands. Whether it is painted is style (the `connector` part), so a `where` can hide some.
+ */
+export type WaterfallConnectorMode = 'between' | 'spanning';
+export declare const WATERFALL_CONNECTOR_MODES: readonly WaterfallConnectorMode[];
+/** Waterfall parameters: both are geometry. `width` the compiler places; `connector` the paint lays out from it. */
+export interface WaterfallGeomParams {
+    /** Bar width as a fraction of the band the discrete scale allocates to the category, in `(0, 1]`. */
+    width?: number;
+    /** How the running total is carried from each bar to the next. Defaults to `'spanning'`. */
+    connector?: WaterfallConnectorMode;
+}
+export declare const readBarWidth: ({ width }: WaterfallGeomParams) => number;
+export declare const readConnectorMode: ({ connector }: WaterfallGeomParams) => WaterfallConnectorMode;
+export declare const isConnectorMode: (value: unknown) => value is WaterfallConnectorMode;

package/licenses/PolyForm-Free-Trial-1.0.0.md

@@ -0,0 +1,93 @@
+# PolyForm Free Trial License 1.0.0
+
+<https://polyformproject.org/licenses/free-trial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software
+to do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose. However, you may only make changes or
+new works based on the software according to [Changes and New
+Works License](#changes-and-new-works-license), and you may
+not distribute copies of the software.
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## Free Trial
+
+Use to evaluate whether the software suits a particular
+application for less than 32 consecutive calendar days, on
+behalf of you or your company, is use for a permitted purpose.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+If you violate any of these terms, or do anything with the
+software not covered by your licenses, all your licenses
+end immediately.
+
+## No Liability
+
+_**As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.**_
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/licenses/PolyForm-NonCommercial-1.0.0.md

@@ -0,0 +1,131 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright Graphy Technologies Ltd. (https://graphy.dev)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+_**As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.**_
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/licenses/PolyForm-Small-Business-1.0.0.md

@@ -0,0 +1,121 @@
+# PolyForm Small Business License 1.0.0
+
+<https://polyformproject.org/licenses/small-business/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright Graphy Technologies Ltd. (https://graphy.dev)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## Small Business
+
+Use of the software for the benefit of your company is use for
+a permitted purpose if your company has fewer than 100 total
+individuals working as employees and independent contractors,
+and less than 1,000,000 USD (2019) total revenue in the prior
+tax year. Adjust this revenue threshold for inflation according
+to the United States Bureau of Labor Statistics' consumer price
+index for all urban consumers, U.S. city average, for all items,
+not seasonally adjusted, with 1982–1984=100 reference base.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+_**As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.**_
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@graphysdk/geom-waterfall",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "author": "Graphy",
+  "description": "Waterfall geom for the Graphy charting SDK (beta)",
+  "homepage": "https://docs.graphy.dev/sdk-next/graph-types/waterfall",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "keywords": [
+    "graphy",
+    "chart",
+    "react",
+    "visualization",
+    "grammar-of-graphics",
+    "waterfall",
+    "waterfall-chart"
+  ],
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE.md",
+    "licenses",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "@graphysdk/react": "^1.9.0-beta.1791447671234"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.1",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "rollup-plugin-node-externals": "^8.1.1",
+    "vite": "^8.1.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.11",
+    "@graphysdk/react": "1.9.0-beta.1791447671234",
+    "@graphytools/eslint-config": "0.0.1",
+    "@graphytools/typescript-config": "0.0.1",
+    "@graphytools/vitest-config": "1.0.0",
+    "@graphysdk/viz-engine": "1.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,json,css,md}": [
+      "prettier --write"
+    ],
+    "*.{ts,tsx}": [
+      "eslint --max-warnings=0 --fix"
+    ]
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "TZ=utc vitest",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit"
+  }
 }