tinybase 8.5.0-beta.3 → 8.5.0

package/@types/ui-react-dom/index.d.ts

@@ -692,7 +692,7 @@ export type SortedTablePaginatorProps = {
  *
  * See the <TableInHtmlTable /> (React) demo for this component in action:
  *
- * ![TableInHtmlTable example](https://beta.tinybase.org/shots/tableinhtmltable-react-demo.png
+ * ![TableInHtmlTable example](https://tinybase.org/shots/tableinhtmltable-react-demo.png
  * "TableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -838,7 +838,7 @@ export function TableInHtmlTable(
  * See the <SortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![SortedTableInHtmlTable example](https://beta.tinybase.org/shots/sortedtableinhtmltable-react-demo.png
+ * ![SortedTableInHtmlTable example](https://tinybase.org/shots/sortedtableinhtmltable-react-demo.png
  * "SortedTableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -1011,7 +1011,7 @@ export function SortedTableInHtmlTable(
  *
  * See the <ValuesInHtmlTable /> (React) demo for this component in action:
  *
- * ![ValuesInHtmlTable example](https://beta.tinybase.org/shots/valuesinhtmltable-react-demo.png
+ * ![ValuesInHtmlTable example](https://tinybase.org/shots/valuesinhtmltable-react-demo.png
  * "ValuesInHtmlTable example")
  *
  * The component's props identify which Row to render based on Table Id, Row Id,
@@ -1142,7 +1142,7 @@ export function ValuesInHtmlTable(
  *
  * See the <SliceInHtmlTable /> (React) demo for this component in action:
  *
- * ![SliceInHtmlTable example](https://beta.tinybase.org/shots/sliceinhtmltable-react-demo.png
+ * ![SliceInHtmlTable example](https://tinybase.org/shots/sliceinhtmltable-react-demo.png
  * "SliceInHtmlTable example")
  *
  * The component's props identify which Slice to render based on Index Id, Slice
@@ -1300,7 +1300,7 @@ export function SliceInHtmlTable(
  * See the <RelationshipInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![RelationshipInHtmlTable example](https://beta.tinybase.org/shots/relationshipinhtmltable-react-demo.png
+ * ![RelationshipInHtmlTable example](https://tinybase.org/shots/relationshipinhtmltable-react-demo.png
  * "RelationshipInHtmlTable example")
  *
  * The component's props identify which Relationship to render based on
@@ -1478,7 +1478,7 @@ export function RelationshipInHtmlTable(
  * See the <ResultTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![ResultTableInHtmlTable example](https://beta.tinybase.org/shots/resulttableinhtmltable-react-demo.png
+ * ![ResultTableInHtmlTable example](https://tinybase.org/shots/resulttableinhtmltable-react-demo.png
  * "ResultTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1631,7 +1631,7 @@ export function ResultTableInHtmlTable(
  * See the <ResultSortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![ResultSortedTableInHtmlTable example](https://beta.tinybase.org/shots/resultsortedtableinhtmltable-react-demo.png
+ * ![ResultSortedTableInHtmlTable example](https://tinybase.org/shots/resultsortedtableinhtmltable-react-demo.png
  * "ResultSortedTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1805,7 +1805,7 @@ export function ResultSortedTableInHtmlTable(
  *
  * See the <EditableCellView /> (React) demo for this component in action:
  *
- * ![EditableCellView example](https://beta.tinybase.org/shots/editablecellview-react-demo.png
+ * ![EditableCellView example](https://tinybase.org/shots/editablecellview-react-demo.png
  * "EditableCellView example")
  *
  * The component's props identify which Cell to render based on Table Id, Row
@@ -1876,7 +1876,7 @@ export function EditableCellView(
  *
  * See the <EditableValueView /> (React) demo for this component in action:
  *
- * ![EditableValueView example](https://beta.tinybase.org/shots/editablevalueview-react-demo.png
+ * ![EditableValueView example](https://tinybase.org/shots/editablevalueview-react-demo.png
  * "EditableValueView example")
  *
  * The component's props identify which Value to render based on Table Id, Row
@@ -1947,7 +1947,7 @@ export function EditableValueView(
  * See the <SortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![SortedTablePaginator example](https://beta.tinybase.org/shots/sortedtablepaginator-react-demo.png
+ * ![SortedTablePaginator example](https://tinybase.org/shots/sortedtablepaginator-react-demo.png
  * "SortedTablePaginator example")
  *
  * The component displays 'previous' and 'next' buttons for paging through the

package/@types/ui-react-dom/with-schemas/index.d.ts

@@ -674,7 +674,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <TableInHtmlTable /> (React) demo for this component in action:
  *
- * ![TableInHtmlTable example](https://beta.tinybase.org/shots/tableinhtmltable-react-demo.png
+ * ![TableInHtmlTable example](https://tinybase.org/shots/tableinhtmltable-react-demo.png
  * "TableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -828,7 +828,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <SortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![SortedTableInHtmlTable example](https://beta.tinybase.org/shots/sortedtableinhtmltable-react-demo.png
+ * ![SortedTableInHtmlTable example](https://tinybase.org/shots/sortedtableinhtmltable-react-demo.png
  * "SortedTableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -1009,7 +1009,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <ValuesInHtmlTable /> (React) demo for this component in action:
  *
- * ![ValuesInHtmlTable example](https://beta.tinybase.org/shots/valuesinhtmltable-react-demo.png
+ * ![ValuesInHtmlTable example](https://tinybase.org/shots/valuesinhtmltable-react-demo.png
  * "ValuesInHtmlTable example")
  *
  * The component's props identify which Row to render based on Table Id, Row Id,
@@ -1148,7 +1148,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <SliceInHtmlTable /> (React) demo for this component in action:
  *
- * ![SliceInHtmlTable example](https://beta.tinybase.org/shots/sliceinhtmltable-react-demo.png
+ * ![SliceInHtmlTable example](https://tinybase.org/shots/sliceinhtmltable-react-demo.png
  * "SliceInHtmlTable example")
  *
  * The component's props identify which Slice to render based on Index Id, Slice
@@ -1314,7 +1314,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <RelationshipInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![RelationshipInHtmlTable example](https://beta.tinybase.org/shots/relationshipinhtmltable-react-demo.png
+ * ![RelationshipInHtmlTable example](https://tinybase.org/shots/relationshipinhtmltable-react-demo.png
  * "RelationshipInHtmlTable example")
  *
  * The component's props identify which Relationship to render based on
@@ -1500,7 +1500,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <ResultTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![ResultTableInHtmlTable example](https://beta.tinybase.org/shots/resulttableinhtmltable-react-demo.png
+ * ![ResultTableInHtmlTable example](https://tinybase.org/shots/resulttableinhtmltable-react-demo.png
  * "ResultTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1661,7 +1661,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <ResultSortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![ResultSortedTableInHtmlTable example](https://beta.tinybase.org/shots/resultsortedtableinhtmltable-react-demo.png
+ * ![ResultSortedTableInHtmlTable example](https://tinybase.org/shots/resultsortedtableinhtmltable-react-demo.png
  * "ResultSortedTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1843,7 +1843,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <EditableCellView /> (React) demo for this component in action:
  *
- * ![EditableCellView example](https://beta.tinybase.org/shots/editablecellview-react-demo.png
+ * ![EditableCellView example](https://tinybase.org/shots/editablecellview-react-demo.png
  * "EditableCellView example")
  *
  * The component's props identify which Cell to render based on Table Id, Row
@@ -1928,7 +1928,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <EditableValueView /> (React) demo for this component in action:
  *
- * ![EditableValueView example](https://beta.tinybase.org/shots/editablevalueview-react-demo.png
+ * ![EditableValueView example](https://tinybase.org/shots/editablevalueview-react-demo.png
  * "EditableValueView example")
  *
  * The component's props identify which Value to render based on Table Id, Row
@@ -1999,7 +1999,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <SortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![SortedTablePaginator example](https://beta.tinybase.org/shots/sortedtablepaginator-react-demo.png
+ * ![SortedTablePaginator example](https://tinybase.org/shots/sortedtablepaginator-react-demo.png
  * "SortedTablePaginator example")
  *
  * The component displays 'previous' and 'next' buttons for paging through the

package/@types/ui-react-dom-charts/index.d.ts

@@ -117,9 +117,10 @@ export type QuerySourceProps = {
 export type BindingProps = {
   /**
    * The Id of the Cell that provides each data point's x value. Finite numbers
-   * can be used as continuous x values in line charts, while strings and
-   * booleans are used as category values. Boolean category labels are rendered
-   * as `true` and `false`.
+   * can be used as continuous linear x values in line charts, ISO date strings
+   * can be used as time x values, and other strings and booleans are used as
+   * category values. Boolean category labels are rendered as `true` and
+   * `false`.
    * @category Prop
    * @since v8.5.0
    */
@@ -175,9 +176,10 @@ export type SeriesProps = {
   readonly className?: string;
   /**
    * The Id of the Cell that provides each data point's x value. Finite numbers
-   * can be used as continuous x values in line series, while strings and
-   * booleans are used as category values. Boolean category labels are rendered
-   * as `true` and `false`.
+   * can be used as continuous linear x values in line series, ISO date strings
+   * can be used as time x values, and other strings and booleans are used as
+   * category values. Boolean category labels are rendered as `true` and
+   * `false`.
    * @category Prop
    * @since v8.5.0
    */
@@ -224,16 +226,35 @@ export type SeriesProps = {
 };
 
 /**
- * The XAxisProps type describes the props that configure the x axis of a
- * CartesianChart component.
- *
- * The x axis is inferred by default. Use an XAxis component child when you want
- * to override its title, numeric bounds, tick values, tick count, tick labels,
- * or SVG class name.
+ * The XAxisScale type describes how x-axis values should be interpreted:
+ * `auto`, `category`, `linear`, or `time`.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type XAxisScale = 'auto' | 'category' | 'linear' | 'time';
+
+/**
+ * The TimestampUnit type describes the unit used by numeric timestamp values on
+ * a time x axis: `millisecond` or `second`.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type TimestampUnit = 'millisecond' | 'second';
+
+/**
+ * The TimeValue type describes values that can be used for explicit bounds and
+ * ticks on a time x axis: numbers, ISO date strings, or Date objects.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type TimeValue = number | string | Date;
+
+/**
+ * The BaseXAxisProps type describes props shared by all x-axis configurations.
  * @category Configuration
  * @since v8.5.0
  */
-export type XAxisProps = {
+export type BaseXAxisProps = {
   /**
    * An optional string that will be added to the class attribute of the x-axis
    * SVG group element.
@@ -249,7 +270,43 @@ export type XAxisProps = {
    */
   readonly title?: string;
   /**
-   * An optional minimum x-axis bound for continuous numeric x values.
+   * An optional preferred number of ticks to render on a continuous x axis.
+   *
+   * The actual number of ticks may vary so that labels remain readable.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tickCount?: number;
+};
+
+/**
+ * The LinearXAxisProps type describes x-axis configuration for automatically
+ * inferred, categorical, and linear axes.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type LinearXAxisProps = BaseXAxisProps & {
+  /**
+   * An optional scale to use for the x axis.
+   *
+   * The default `auto` scale infers linear axes from numeric line-series x
+   * values, time axes from ISO date strings, and category axes otherwise. Use
+   * `time` explicitly for numeric Unix timestamp values.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly scale?: 'auto' | 'category' | 'linear';
+  /**
+   * The unit for numeric timestamp values on a time x axis.
+   *
+   * This prop is ignored unless the scale prop is `time`, and defaults to
+   * `millisecond`.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly timestampUnit?: never;
+  /**
+   * An optional minimum x-axis bound for continuous numeric or time x values.
    *
    * This prop is ignored when the x axis is categorical.
    * @category Prop
@@ -257,7 +314,7 @@ export type XAxisProps = {
    */
   readonly min?: number;
   /**
-   * An optional maximum x-axis bound for continuous numeric x values.
+   * An optional maximum x-axis bound for continuous numeric or time x values.
    *
    * This prop is ignored when the x axis is categorical.
    * @category Prop
@@ -265,7 +322,7 @@ export type XAxisProps = {
    */
   readonly max?: number;
   /**
-   * Optional numeric tick values to use for a continuous x axis.
+   * Optional tick values to use for a continuous numeric or time x axis.
    *
    * This prop is ignored when the x axis is categorical.
    * @category Prop
@@ -273,24 +330,90 @@ export type XAxisProps = {
    */
   readonly ticks?: readonly number[];
   /**
-   * An optional preferred number of ticks to render on a continuous x axis.
+   * An optional function for formatting x-axis tick labels.
    *
-   * The actual number of ticks may vary so that labels remain readable.
+   * It receives the original tick value for category axes, the numeric tick
+   * value for linear axes, or a Date object for time axes. For time axes, the
+   * normalized epoch millisecond timestamp is provided as a second argument.
    * @category Prop
    * @since v8.5.0
    */
-  readonly tickCount?: number;
+  readonly tickFormatter?: (tick: boolean | number | string) => string;
+};
+
+/**
+ * The TimeXAxisProps type describes x-axis configuration for time axes.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type TimeXAxisProps = BaseXAxisProps & {
+  /**
+   * An optional scale to use for the x axis.
+   *
+   * The default `auto` scale infers linear axes from numeric line-series x
+   * values, time axes from ISO date strings, and category axes otherwise. Use
+   * `time` explicitly for numeric Unix timestamp values.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly scale: 'time';
+  /**
+   * The unit for numeric timestamp values on a time x axis.
+   *
+   * This prop is ignored unless the scale prop is `time`, and defaults to
+   * `millisecond`.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly timestampUnit?: TimestampUnit;
+  /**
+   * An optional minimum x-axis bound for continuous numeric or time x values.
+   *
+   * This prop is ignored when the x axis is categorical.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly min?: TimeValue;
+  /**
+   * An optional maximum x-axis bound for continuous numeric or time x values.
+   *
+   * This prop is ignored when the x axis is categorical.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly max?: TimeValue;
+  /**
+   * Optional tick values to use for a continuous numeric or time x axis.
+   *
+   * This prop is ignored when the x axis is categorical.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly ticks?: readonly TimeValue[];
   /**
    * An optional function for formatting x-axis tick labels.
    *
-   * It receives the original tick value, which can be a finite number, string,
-   * or boolean.
+   * It receives the original tick value for category axes, the numeric tick
+   * value for linear axes, or a Date object for time axes. For time axes, the
+   * normalized epoch millisecond timestamp is provided as a second argument.
    * @category Prop
    * @since v8.5.0
    */
-  readonly tickFormatter?: (tick: boolean | number | string) => string;
+  readonly tickFormatter?: (tick: Date, timestamp: number) => string;
 };
 
+/**
+ * The XAxisProps type describes the props that configure the x axis of a
+ * CartesianChart component, LineChart component, or BarChart component.
+ *
+ * The x axis is inferred by default. Use an XAxis component child when you
+ * want to override its title, scale, continuous bounds, tick values, tick
+ * count, tick labels, or SVG class name.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type XAxisProps = LinearXAxisProps | TimeXAxisProps;
+
 /**
  * The YAxisProps type describes the props that configure the y axis of a
  * CartesianChart component.
@@ -360,7 +483,7 @@ export type YAxisProps = {
  *
  * See the Composing Charts (React) demo for this component in action:
  *
- * ![CartesianChart component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
+ * ![CartesianChart component example](https://tinybase.org/shots/composing-charts-react-demo.png
  * "CartesianChart component example")
  *
  * The series children declare their own xCellId and yCellId bindings. The
@@ -410,15 +533,16 @@ export function CartesianChart(
 ): ComponentReturnType;
 
 /**
- * The XAxis component configures the x axis of a CartesianChart component.
+ * The XAxis component configures the x axis of a CartesianChart component,
+ * LineChart component, or BarChart component.
  *
  * It is a configuration child rather than a separately rendered SVG element:
- * include zero or one XAxis component in a CartesianChart component's children.
- * If omitted, the x axis is inferred from the chart's series.
+ * include zero or one XAxis component in a chart's children. If omitted, the x
+ * axis is inferred from the chart's series.
  *
  * See the Axis Overrides (React) demo for this component in action:
  *
- * ![XAxis component example](https://beta.tinybase.org/shots/axis-overrides-react-demo.png
+ * ![XAxis component example](https://tinybase.org/shots/axis-overrides-react-demo.png
  * "XAxis component example")
  * @category Store components
  * @since v8.5.0
@@ -434,7 +558,7 @@ export function XAxis(props: XAxisProps): ComponentReturnType;
  *
  * See the Axis Overrides (React) demo for this component in action:
  *
- * ![YAxis component example](https://beta.tinybase.org/shots/axis-overrides-react-demo.png
+ * ![YAxis component example](https://tinybase.org/shots/axis-overrides-react-demo.png
  * "YAxis component example")
  * @category Store components
  * @since v8.5.0
@@ -444,13 +568,13 @@ export function YAxis(props: YAxisProps): ComponentReturnType;
 /**
  * The LineSeries component renders a line series in a CartesianChart component.
  * If every x value in every series is a finite number, the x axis is rendered
- * as a continuous numeric scale. If any x value is a string or boolean, the x
- * axis is rendered categorically. When sortCellId is omitted, rows are sorted
- * by xCellId.
+ * as a continuous linear scale. ISO date strings are inferred as a time scale.
+ * Other strings and booleans are rendered categorically. When sortCellId is
+ * omitted, rows are sorted by xCellId.
  *
  * See the Composing Charts (React) demo for this component in action:
  *
- * ![LineSeries component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
+ * ![LineSeries component example](https://tinybase.org/shots/composing-charts-react-demo.png
  * "LineSeries component example")
  * @category Store components
  * @since v8.5.0
@@ -459,12 +583,14 @@ export function LineSeries(props: SeriesProps): ComponentReturnType;
 
 /**
  * The BarSeries component renders a bar series in a CartesianChart component.
- * Its x values are always rendered categorically, even when they are finite
- * numbers. Boolean category labels are rendered as `true` and `false`.
+ * Its x values are rendered categorically by default, even when they are finite
+ * numbers. Add an XAxis component with a `linear` or `time` scale to position
+ * bars continuously. Boolean category labels are rendered as `true` and
+ * `false`.
  *
  * See the Composing Charts (React) demo for this component in action:
  *
- * ![BarSeries component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
+ * ![BarSeries component example](https://tinybase.org/shots/composing-charts-react-demo.png
  * "BarSeries component example")
  * @category Store components
  * @since v8.5.0
@@ -473,13 +599,15 @@ export function BarSeries(props: SeriesProps): ComponentReturnType;
 
 /**
  * The LineChart component renders a line chart from TinyBase data. If every x
- * value is a finite number, the x axis is rendered as a continuous numeric
- * scale. If any x value is a string or boolean, the x axis is rendered
- * categorically. When sortCellId is omitted, rows are sorted by xCellId.
+ * value is a finite number, the x axis is rendered as a continuous linear
+ * scale. ISO date strings are inferred as a time scale. Other strings and
+ * booleans are rendered categorically. Add XAxis component and YAxis component
+ * children to override axis configuration. When sortCellId is omitted, rows are
+ * sorted by xCellId.
  *
  * See the <LineChart /> (React) demo for this component in action:
  *
- * ![LineChart component example](https://beta.tinybase.org/shots/basic-chart-react-demo.png "LineChart
+ * ![LineChart component example](https://tinybase.org/shots/basic-chart-react-demo.png "LineChart
  * component example")
  * @category Store components
  * @since v8.5.0
@@ -519,17 +647,20 @@ export function BarSeries(props: SeriesProps): ComponentReturnType;
  * ```
  */
 export function LineChart(
-  props: (TableSourceProps | QuerySourceProps) & BindingProps & ChartProps,
+  props: (TableSourceProps | QuerySourceProps) &
+    BindingProps &
+    ChartProps & {readonly children?: ReactNode},
 ): ComponentReturnType;
 
 /**
  * The BarChart component renders a bar chart from TinyBase data. Its x values
- * are always rendered categorically, even when they are finite numbers. Boolean
- * category labels are rendered as `true` and `false`.
+ * are rendered categorically by default, even when they are finite numbers. Add
+ * an XAxis component with a `linear` or `time` scale to position bars
+ * continuously. Boolean category labels are rendered as `true` and `false`.
  *
  * See the Sorting And Types (React) demo for this component in action:
  *
- * ![BarChart component example](https://beta.tinybase.org/shots/sorting-and-types-react-demo.png
+ * ![BarChart component example](https://tinybase.org/shots/sorting-and-types-react-demo.png
  * "BarChart component example")
  * @category Store components
  * @since v8.5.0
@@ -570,5 +701,7 @@ export function LineChart(
  * ```
  */
 export function BarChart(
-  props: (TableSourceProps | QuerySourceProps) & BindingProps & ChartProps,
+  props: (TableSourceProps | QuerySourceProps) &
+    BindingProps &
+    ChartProps & {readonly children?: ReactNode},
 ): ComponentReturnType;