@planningcenter/tapestry 4.14.0 → 4.15.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/dist/components/DataTable/ActiveFilters.d.ts +6 -1
  2. package/dist/components/DataTable/ActiveFilters.d.ts.map +1 -1
  3. package/dist/components/DataTable/ActiveFilters.js +18 -10
  4. package/dist/components/DataTable/ActiveFilters.js.map +1 -1
  5. package/dist/components/DataTable/CollectionEditorsStatic.js +2 -2
  6. package/dist/components/DataTable/CollectionEditorsStatic.js.map +1 -1
  7. package/dist/components/DataTable/DataTable.d.ts +8 -5
  8. package/dist/components/DataTable/DataTable.d.ts.map +1 -1
  9. package/dist/components/DataTable/DataTable.js +26 -14
  10. package/dist/components/DataTable/DataTable.js.map +1 -1
  11. package/dist/components/DataTable/DataTableColumn.d.ts +12 -3
  12. package/dist/components/DataTable/DataTableColumn.d.ts.map +1 -1
  13. package/dist/components/DataTable/DataTableColumnTypes.js +4 -4
  14. package/dist/components/DataTable/DataTableColumnTypes.js.map +1 -1
  15. package/dist/components/DataTable/ResultsCount.d.ts +2 -2
  16. package/dist/components/DataTable/ResultsCount.d.ts.map +1 -1
  17. package/dist/components/DataTable/ResultsCount.js +8 -7
  18. package/dist/components/DataTable/ResultsCount.js.map +1 -1
  19. package/dist/components/DataTable/SelectAllBanner.d.ts.map +1 -1
  20. package/dist/components/DataTable/SelectAllBanner.js +5 -3
  21. package/dist/components/DataTable/SelectAllBanner.js.map +1 -1
  22. package/dist/components/DataTable/TableActions.d.ts.map +1 -1
  23. package/dist/components/DataTable/TableActions.js +5 -3
  24. package/dist/components/DataTable/TableActions.js.map +1 -1
  25. package/dist/components/DataTable/dateFilter.js +28 -10
  26. package/dist/components/DataTable/dateFilter.js.map +1 -1
  27. package/dist/components/DataTable/dayFilter.js +4 -3
  28. package/dist/components/DataTable/dayFilter.js.map +1 -1
  29. package/dist/components/DataTable/numberFilter.js +2 -2
  30. package/dist/components/DataTable/numberFilter.js.map +1 -1
  31. package/dist/components/DataTable/useIsNarrowViewport.d.ts.map +1 -1
  32. package/dist/components/DataTable/useIsNarrowViewport.js +3 -1
  33. package/dist/components/DataTable/useIsNarrowViewport.js.map +1 -1
  34. package/dist/components/DataTable/useResultsAnnouncement.d.ts.map +1 -1
  35. package/dist/components/DataTable/useResultsAnnouncement.js +3 -1
  36. package/dist/components/DataTable/useResultsAnnouncement.js.map +1 -1
  37. package/dist/components/DataTable/useSavedViewsClient.d.ts +9 -2
  38. package/dist/components/DataTable/useSavedViewsClient.d.ts.map +1 -1
  39. package/dist/components/DataTable/useSavedViewsClient.js +9 -2
  40. package/dist/components/DataTable/useSavedViewsClient.js.map +1 -1
  41. package/dist/components/DataTable/useShelfExpanded.d.ts +4 -3
  42. package/dist/components/DataTable/useShelfExpanded.d.ts.map +1 -1
  43. package/dist/components/DataTable/useShelfExpanded.js +21 -5
  44. package/dist/components/DataTable/useShelfExpanded.js.map +1 -1
  45. package/dist/components/DataTable/views.js +1 -4
  46. package/dist/components/DataTable/views.js.map +1 -1
  47. package/dist/components/button/ActionsDropdownIconButton.js +1 -1
  48. package/dist/components/button/ActionsDropdownIconButton.js.map +1 -1
  49. package/dist/components/button/IconButton.js +1 -1
  50. package/dist/components/button/IconButton.js.map +1 -1
  51. package/dist/components/combo-box/ComboBox.d.ts.map +1 -1
  52. package/dist/components/combo-box/ComboBox.js +17 -2
  53. package/dist/components/combo-box/ComboBox.js.map +1 -1
  54. package/dist/components/currency-input/CurrencyInput.d.ts +1 -1
  55. package/dist/components/currency-input/CurrencyInput.d.ts.map +1 -1
  56. package/dist/components/currency-input/CurrencyInput.js +4 -1
  57. package/dist/components/currency-input/CurrencyInput.js.map +1 -1
  58. package/dist/components/date-picker/DatePicker.d.ts +1 -1
  59. package/dist/components/date-picker/DatePicker.d.ts.map +1 -1
  60. package/dist/components/date-picker/DatePicker.js +72 -69
  61. package/dist/components/date-picker/DatePicker.js.map +1 -1
  62. package/dist/components/link/IconLink.js +1 -1
  63. package/dist/components/link/IconLink.js.map +1 -1
  64. package/dist/components/segmented-control/IconSegment.js +1 -1
  65. package/dist/components/segmented-control/IconSegment.js.map +1 -1
  66. package/dist/components/time-field/TimeField.d.ts.map +1 -1
  67. package/dist/components/time-field/TimeField.js +12 -9
  68. package/dist/components/time-field/TimeField.js.map +1 -1
  69. package/dist/reactRender.css +384 -379
  70. package/dist/reactRender.css.map +1 -1
  71. package/dist/reactRenderLegacy.css +384 -379
  72. package/dist/reactRenderLegacy.css.map +1 -1
  73. package/dist/tapestryMount.css +384 -379
  74. package/dist/tapestryMount.css.map +1 -1
  75. package/dist/tapestryMountLegacy.css +384 -379
  76. package/dist/tapestryMountLegacy.css.map +1 -1
  77. package/dist/unstable.css +5 -0
  78. package/dist/unstable.css.map +1 -1
  79. package/dist/utilities/locale.d.ts +4 -4
  80. package/dist/utilities/locale.js +5 -34
  81. package/dist/utilities/locale.js.map +1 -1
  82. package/dist/utilities/useDateFieldLocale.js +2 -2
  83. package/dist/utilities/useDateFieldLocale.js.map +1 -1
  84. package/docs/components/DataTable.md +158 -0
  85. package/docs/llms.txt +3 -0
  86. package/package.json +5 -3
@@ -1,9 +1,9 @@
1
1
  import React, { type ReactNode } from "react";
2
2
  /**
3
- * Sets the locale DataTable formats dates with, app-wide. Call once at boot,
4
- * before the first render; later calls don't re-render mounted components.
5
- * An `I18nProvider` overrides it for its subtree. Pass `undefined` to fall
6
- * back to the browser locale.
3
+ * Sets the locale DataTable, DatePicker and TimeField format dates with,
4
+ * app-wide. Call once at boot, before the first render; later calls don't
5
+ * re-render mounted components. An `I18nProvider` overrides it for its
6
+ * subtree. Pass `undefined` to fall back to the browser locale.
7
7
  */
8
8
  export declare function setLocale(locale: string | undefined): void;
9
9
  export interface I18nProviderProps {
@@ -1,39 +1,10 @@
1
- import React__default, { createContext, useContext } from 'react';
2
- import { I18nProvider as I18nProvider$1, useLocale } from 'react-aria/I18nProvider';
1
+ import { createContext, useContext } from 'react';
2
+ import { useLocale } from 'react-aria/I18nProvider';
3
3
 
4
- let globalLocale;
5
- /**
6
- * Sets the locale DataTable formats dates with, app-wide. Call once at boot,
7
- * before the first render; later calls don't re-render mounted components.
8
- * An `I18nProvider` overrides it for its subtree. Pass `undefined` to fall
9
- * back to the browser locale.
10
- */
11
- function setLocale(locale) {
12
- globalLocale = locale;
13
- }
14
4
  function canonicalLocale(locale) {
15
- if (!locale)
16
- return undefined;
17
- try {
18
- return Intl.getCanonicalLocales(locale)[0];
19
- }
20
- catch {
21
- return undefined;
22
- }
5
+ return undefined;
23
6
  }
24
7
  const LocaleContext = createContext(undefined);
25
- /**
26
- * Sets the locale for a subtree, overriding `setLocale`. Use this instead of
27
- * importing `I18nProvider` from `react-aria`: Tapestry can't see a provider
28
- * from a separately installed copy. An invalid locale is ignored.
29
- */
30
- function I18nProvider({ children, locale }) {
31
- const validLocale = canonicalLocale(locale);
32
- if (!validLocale)
33
- return React__default.createElement(React__default.Fragment, null, children);
34
- return (React__default.createElement(LocaleContext.Provider, { value: validLocale },
35
- React__default.createElement(I18nProvider$1, { locale: validLocale }, children)));
36
- }
37
8
  /**
38
9
  * Resolves the nearest `I18nProvider`, then `setLocale`, then the browser
39
10
  * locale. An invalid locale falls through to the next one.
@@ -41,8 +12,8 @@ function I18nProvider({ children, locale }) {
41
12
  function useTapestryLocale() {
42
13
  const providerLocale = useContext(LocaleContext);
43
14
  const { locale: defaultLocale } = useLocale();
44
- return providerLocale ?? canonicalLocale(globalLocale) ?? defaultLocale;
15
+ return providerLocale ?? canonicalLocale() ?? defaultLocale;
45
16
  }
46
17
 
47
- export { I18nProvider, setLocale, useTapestryLocale };
18
+ export { useTapestryLocale };
48
19
  //# sourceMappingURL=locale.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"locale.js","sources":["../../src/utilities/locale.tsx"],"sourcesContent":["import React, { createContext, type ReactNode, useContext } from \"react\"\nimport {\n I18nProvider as AriaI18nProvider,\n useLocale,\n} from \"react-aria/I18nProvider\"\n\nlet globalLocale: string | undefined\n\n/**\n * Sets the locale DataTable formats dates with, app-wide. Call once at boot,\n * before the first render; later calls don't re-render mounted components.\n * An `I18nProvider` overrides it for its subtree. Pass `undefined` to fall\n * back to the browser locale.\n */\nexport function setLocale(locale: string | undefined) {\n globalLocale = locale\n}\n\nfunction canonicalLocale(locale: string | undefined) {\n if (!locale) return undefined\n try {\n return Intl.getCanonicalLocales(locale)[0]\n } catch {\n return undefined\n }\n}\n\nconst LocaleContext = createContext<string | undefined>(undefined)\n\nexport interface I18nProviderProps {\n children: ReactNode\n /** A BCP 47 language tag, e.g. `en-GB`. */\n locale: string\n}\n\n/**\n * Sets the locale for a subtree, overriding `setLocale`. Use this instead of\n * importing `I18nProvider` from `react-aria`: Tapestry can't see a provider\n * from a separately installed copy. An invalid locale is ignored.\n */\nexport function I18nProvider({ children, locale }: I18nProviderProps) {\n const validLocale = canonicalLocale(locale)\n if (!validLocale) return <>{children}</>\n\n return (\n <LocaleContext.Provider value={validLocale}>\n <AriaI18nProvider locale={validLocale}>{children}</AriaI18nProvider>\n </LocaleContext.Provider>\n )\n}\n\n/**\n * Resolves the nearest `I18nProvider`, then `setLocale`, then the browser\n * locale. An invalid locale falls through to the next one.\n */\nexport function useTapestryLocale() {\n const providerLocale = useContext(LocaleContext)\n const { locale: defaultLocale } = useLocale()\n return providerLocale ?? canonicalLocale(globalLocale) ?? defaultLocale\n}\n"],"names":["React","AriaI18nProvider"],"mappings":";;;AAMA,IAAI,YAAgC;AAEpC;;;;;AAKG;AACG,SAAU,SAAS,CAAC,MAA0B,EAAA;IAClD,YAAY,GAAG,MAAM;AACvB;AAEA,SAAS,eAAe,CAAC,MAA0B,EAAA;AACjD,IAAA,IAAI,CAAC,MAAM;AAAE,QAAA,OAAO,SAAS;AAC7B,IAAA,IAAI;QACF,OAAO,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5C;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;AAEA,MAAM,aAAa,GAAG,aAAa,CAAqB,SAAS,CAAC;AAQlE;;;;AAIG;SACa,YAAY,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAqB,EAAA;AAClE,IAAA,MAAM,WAAW,GAAG,eAAe,CAAC,MAAM,CAAC;AAC3C,IAAA,IAAI,CAAC,WAAW;QAAE,OAAOA,cAAA,CAAA,aAAA,CAAAA,cAAA,CAAA,QAAA,EAAA,IAAA,EAAG,QAAQ,CAAI;IAExC,QACEA,6BAAC,aAAa,CAAC,QAAQ,EAAA,EAAC,KAAK,EAAE,WAAW,EAAA;QACxCA,cAAA,CAAA,aAAA,CAACC,cAAgB,EAAA,EAAC,MAAM,EAAE,WAAW,IAAG,QAAQ,CAAoB,CAC7C;AAE7B;AAEA;;;AAGG;SACa,iBAAiB,GAAA;AAC/B,IAAA,MAAM,cAAc,GAAG,UAAU,CAAC,aAAa,CAAC;IAChD,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,SAAS,EAAE;IAC7C,OAAO,cAAc,IAAI,eAAe,CAAC,YAAY,CAAC,IAAI,aAAa;AACzE;;;;"}
1
+ {"version":3,"file":"locale.js","sources":["../../src/utilities/locale.tsx"],"sourcesContent":["import React, { createContext, type ReactNode, useContext } from \"react\"\nimport {\n I18nProvider as AriaI18nProvider,\n useLocale,\n} from \"react-aria/I18nProvider\"\n\nlet globalLocale: string | undefined\n\n/**\n * Sets the locale DataTable, DatePicker and TimeField format dates with,\n * app-wide. Call once at boot, before the first render; later calls don't\n * re-render mounted components. An `I18nProvider` overrides it for its\n * subtree. Pass `undefined` to fall back to the browser locale.\n */\nexport function setLocale(locale: string | undefined) {\n globalLocale = locale\n}\n\nfunction canonicalLocale(locale: string | undefined) {\n if (!locale) return undefined\n try {\n return Intl.getCanonicalLocales(locale)[0]\n } catch {\n return undefined\n }\n}\n\nconst LocaleContext = createContext<string | undefined>(undefined)\n\nexport interface I18nProviderProps {\n children: ReactNode\n /** A BCP 47 language tag, e.g. `en-GB`. */\n locale: string\n}\n\n/**\n * Sets the locale for a subtree, overriding `setLocale`. Use this instead of\n * importing `I18nProvider` from `react-aria`: Tapestry can't see a provider\n * from a separately installed copy. An invalid locale is ignored.\n */\nexport function I18nProvider({ children, locale }: I18nProviderProps) {\n const validLocale = canonicalLocale(locale)\n if (!validLocale) return <>{children}</>\n\n return (\n <LocaleContext.Provider value={validLocale}>\n <AriaI18nProvider locale={validLocale}>{children}</AriaI18nProvider>\n </LocaleContext.Provider>\n )\n}\n\n/**\n * Resolves the nearest `I18nProvider`, then `setLocale`, then the browser\n * locale. An invalid locale falls through to the next one.\n */\nexport function useTapestryLocale() {\n const providerLocale = useContext(LocaleContext)\n const { locale: defaultLocale } = useLocale()\n return providerLocale ?? canonicalLocale(globalLocale) ?? defaultLocale\n}\n"],"names":[],"mappings":";;;AAkBA,SAAS,eAAe,CAAC,MAA0B,EAAA;AACjD,IAAa,OAAO,SAAS;AAM/B;AAEA,MAAM,aAAa,GAAG,aAAa,CAAqB,SAAS,CAAC;AAwBlE;;;AAGG;SACa,iBAAiB,GAAA;AAC/B,IAAA,MAAM,cAAc,GAAG,UAAU,CAAC,aAAa,CAAC;IAChD,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,SAAS,EAAE;IAC7C,OAAO,cAAc,IAAI,eAAe,CAAa,CAAC,IAAI,aAAa;AACzE;;;;"}
@@ -1,9 +1,9 @@
1
1
  import { dateFieldSafeLocale } from './dateFieldLocale.js';
2
+ import { useTapestryLocale } from './locale.js';
2
3
  import { useMemo } from 'react';
3
- import { useLocale } from 'react-aria/I18nProvider';
4
4
 
5
5
  function useDateFieldLocale() {
6
- const { locale } = useLocale();
6
+ const locale = useTapestryLocale();
7
7
  return useMemo(() => dateFieldSafeLocale(locale), [locale]);
8
8
  }
9
9
 
@@ -1 +1 @@
1
- {"version":3,"file":"useDateFieldLocale.js","sources":["../../src/utilities/useDateFieldLocale.ts"],"sourcesContent":["import { dateFieldSafeLocale } from \"@utilities/dateFieldLocale\"\nimport { useMemo } from \"react\"\nimport { useLocale } from \"react-aria/I18nProvider\"\n\nexport function useDateFieldLocale() {\n const { locale } = useLocale()\n return useMemo(() => dateFieldSafeLocale(locale), [locale])\n}\n"],"names":[],"mappings":";;;;SAIgB,kBAAkB,GAAA;AAChC,IAAA,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE;AAC9B,IAAA,OAAO,OAAO,CAAC,MAAM,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;AAC7D;;;;"}
1
+ {"version":3,"file":"useDateFieldLocale.js","sources":["../../src/utilities/useDateFieldLocale.ts"],"sourcesContent":["import { dateFieldSafeLocale } from \"@utilities/dateFieldLocale\"\nimport { useTapestryLocale } from \"@utilities/locale\"\nimport { useMemo } from \"react\"\n\nexport function useDateFieldLocale() {\n const locale = useTapestryLocale()\n return useMemo(() => dateFieldSafeLocale(locale), [locale])\n}\n"],"names":[],"mappings":";;;;SAIgB,kBAAkB,GAAA;AAChC,IAAA,MAAM,MAAM,GAAG,iBAAiB,EAAE;AAClC,IAAA,OAAO,OAAO,CAAC,MAAM,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;AAC7D;;;;"}
@@ -0,0 +1,158 @@
1
+ ---
2
+ use_when:
3
+ - showing a list of records people scan, sort, filter or act on, like people, groups or donations
4
+ - a list that needs search, filters, saved views, pagination or bulk actions
5
+ - comparing the same fields across many items in columns
6
+ ---
7
+
8
+ # DataTable
9
+
10
+ ## Rules
11
+
12
+ - **Do** show every filter that narrows the results as a filter chip, including the filters a default view applies, so people can see why rows are missing.
13
+ - **Do** Make the subset most people want, like active people, the default view: a system view (`staticViews`) set as the default with `initialDefaultViewId`.
14
+ - **Do** Make the row the way to open its item (`getRowLink` or `onRowClick`). Put every other action in `rowActions`.
15
+ - **Do** Name the records with `resultNoun`, like `["person", "people"]`. It labels the count (“1,240 people”), the table and the pagination for screen readers.
16
+ - **Do** Write an `emptyState` that says why the table is empty and, when it helps, how to change that.
17
+ - **Do** Set `pii` on every column that could hold personal information, like names, emails or notes. When unsure, set it.
18
+ - **Don't** Add filters that don’t narrow the results, like a status filter with every status picked. They take up room and suggest the list is missing something.
19
+ - **Don't** Filter rows out behind the scenes. If a filter narrows the results, show it as a chip so people can see it and remove it.
20
+ - **Don't** Put buttons or links inside cells; use `getRowLink`, `onRowClick` or `rowActions` instead. Controls in cells compete with the row’s own action and make keyboard and screen reader navigation harder.
21
+ - **Don't** Add your own search input above the table; set `searchable` instead.
22
+ - **Don't** Store views in the browser or build your own view storage; use tapestry-rails saved views, which store each person’s views on the server.
23
+
24
+ ## Guidelines
25
+
26
+ ### When to use
27
+
28
+ - Use when people need to find, compare or act on records that share the same fields.
29
+ - Use for long or growing lists that need search, filters, sorting or pagination.
30
+ - Don’t use for layout, or for a short list of a few items with no columns to compare; use a plain list instead.
31
+ - Don’t use it as a spreadsheet. Open the item, on a page or in a modal, to edit it.
32
+
33
+ ### Anatomy
34
+
35
+ From top to bottom, a DataTable can show:
36
+
37
+ | Part | What it does | Shown when |
38
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
39
+ | Views bar | Lists the views, starting with “All”. People switch, save and manage views here. | `staticViews` or `initialSavedViews` is set |
40
+ | Results count | Names how many records match, like “1,240 people”, or “2 of 100” when rows are selected. | `resultNoun` is set |
41
+ | Table actions | Icon buttons for actions on the selected rows or the whole table, next to the count. | `tableActions` is set |
42
+ | Search | Finds rows by text. | `searchable` is set |
43
+ | Filters button | Opens the “Add filter” menu and shows or hides the filters shelf. | `filters` is set |
44
+ | View settings | Lets people show and hide columns. | At least one column is `hideable` |
45
+ | Filters shelf | Holds the filter chips and Clear filters. On a changed saved view, it also offers Update view, Save as new view and Discard changes. | A filter is applied. It opens when the first filter is added and closes when the last is removed. |
46
+ | Select-all banner | Offers to select every matching record, not just this page. | `canSelectAllPages` and `resultCount` are set, and the whole page is selected |
47
+ | Table | Column headers (sortable ones show a caret), rows, an optional checkbox column, and a row actions column pinned to the right. | Always |
48
+ | Pagination | Page controls below the table. | `totalPages` is 2 or more, or `paginationType="indexed"` |
49
+
50
+ Only include the parts the table needs. A short list with no filters or views is just the table.
51
+
52
+ ### Filters
53
+
54
+ Filter chips are the table’s record of what it’s showing. Someone looking at the table should be able to tell from the chips alone why each row is there and why others aren’t.
55
+
56
+ - **Show every filter that segments the results.** Any filter that removes rows from the full set appears as a chip, whether a person added it, a view applied it, or the page loaded with it.
57
+ - **Leave out filters that don’t reduce the results.** A filter that matches everything, like “Status is Active, Inactive or Pending” when those are the only statuses, adds a chip without changing a row. Don’t add it, and don’t save it into a view.
58
+ - **A table that only ever shows one set doesn’t need a chip for it.** The members of the group whose page it’s on, for example. Name the set in the page header instead. If people can ever see beyond that set in the same table, it’s a filter and needs a chip.
59
+ - **Only make filterable what people filter by.** Start with the fields people ask about, and group related filters under section headers in the filter tree. A long filter menu hides the filters people need.
60
+ - **Use each filter’s default operators,** like “is”, “contains” or “is before”. They’re chosen for each data type, so the same kind of column filters the same way across Planning Center. Adjust them with `includes` and `excludes` only when a column needs something different.
61
+ - **Search isn’t a filter.** The query doesn’t show as a chip, isn’t saved with views, and stays when a view is applied. Don’t build views around a search.
62
+
63
+ ### Views
64
+
65
+ A view is a named set of filters, sort and visible columns, so people can get back to a list they use often. There are two kinds:
66
+
67
+ | Kind | Prop | Use for |
68
+ | ----------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
69
+ | System view | `staticViews` | Views the app provides for every person, like “Active” or “Needs follow-up”. People can’t rename or delete them. |
70
+ | Saved view | `initialSavedViews` | Views a person creates for themselves. Stored per person by tapestry-rails. |
71
+
72
+ > **System view or static view?**
73
+ >
74
+ > Same thing. Design calls them system views; the prop, the code and the API docs call them static views.
75
+
76
+ - **“All” is always first.** The table adds it, so the full set is always one click away. It can’t be removed. A system view with the id `"initial"` replaces it, for the rare table that has a reason not to start from everything.
77
+ - **Default views can have filters.** When most people come to the table for a subset, make that subset the default rather than making everyone filter it each visit.
78
+ - **Use a system view for a filtered default.** Add the subset to `staticViews` and pass its id as `initialDefaultViewId`. Its filters show as chips like any other filters, so people can see what’s hidden and switch to “All”.
79
+ - **Load the default view’s results on first render.** The table doesn’t apply the default view; it only selects it when the first `activeFilters`, sort and visible columns match it. Load the page with the default view’s filters so the view and the rows agree.
80
+ - **Name views for what they show,** 1–3 words in sentence case, like “Active” or “Joined this year”. Don’t name them for who uses them or what they’re for; people pick a view by what they expect to see.
81
+ - **Keep system views few.** Add one when many people need the same subset. Leave narrower subsets to saved views, so the views bar stays short.
82
+
83
+ How people manage saved views:
84
+
85
+ - **Changing a view:** changing the filters, sort or columns of a saved view marks it changed. The filters shelf then offers **Update view**, **Save as new view** and **Discard changes**, so nothing is saved over by accident.
86
+ - **Create, rename, duplicate, delete, reorder and set as default:** from the view’s menu and **Manage views**. Each action only appears when the app handles it; tapestry-rails and `useSavedViewsClient` handle all of them. See Saved views.
87
+
88
+ ### Columns
89
+
90
+ - **Lead with the column people identify the row by,** usually the name, and keep it always visible (not `hideable`). People scan down it to find the row they want.
91
+ - **Pick the column `type` that matches the data:** `string`, `number`, `currency`, `date`, `datetime`, `boolean`, `enum`, `avatar` or `custom`. It sets the formatting and alignment, so numbers and currency line up at the end where they’re easy to compare. `currency` is in beta and only formats US dollars.
92
+ - **Keep `render` to content.** Text, badges and avatars are fine. Return no buttons or links.
93
+ - **Mark optional columns `hideable`** so people can show the ones they need.
94
+ - **Make a column `sortable`** when people need to order by it, like a name or date.
95
+ - **Set `pii` on columns with personal information.** Session-replay and analytics tools redact them. It has no visible effect.
96
+
97
+ | Set `pii` on | Skip it on |
98
+ | --------------------------------------------------------------------- | -------------------------------------- |
99
+ | Names, emails, phone numbers, addresses, birthdates | System timestamps, like “Submitted at” |
100
+ | Notes, comments and custom form answers, since they can hold anything | Counts, statuses and IDs |
101
+
102
+ ### Actions
103
+
104
+ | Need | Use |
105
+ | ------------------------------------------------------- | ------------------------------------------------------- |
106
+ | Open the row’s item | `getRowLink` (preferred) or `onRowClick` |
107
+ | Act on one row, like edit, archive or remove | `rowActions` |
108
+ | Act on the selected rows, or the whole table | `tableActions`, with `selectable` for the selected rows |
109
+ | Open a related item, like a household’s primary contact | A row action, or a link on the opened item |
110
+
111
+ - Prefer `getRowLink` over `onRowClick` when the item has its own page, so people can open it in a new tab.
112
+ - One row action shows as a button. Two or more go in a menu. Put destructive actions last, with `kind="destructive"`.
113
+ - Table actions are icon buttons, so give each a short `label`. It becomes the tooltip and the accessible name.
114
+
115
+ ### Selection
116
+
117
+ - `selectable` adds a checkbox to each row and a select-all checkbox in the header. The header checkbox selects only the rows on this page.
118
+ - For bulk actions that should reach rows on other pages, set `canSelectAllPages` and pass `resultCount`. Selecting the whole page then shows a banner that offers to select every matching record. Without `resultCount`, the banner isn’t offered, since the table can’t say how many it would select.
119
+ - Selection clears when the search or filters change, so actions never apply to rows people can no longer see.
120
+ - When rows have no `getRowLink` or `onRowClick`, clicking anywhere on a row selects it.
121
+ - Use `disabledKeys` for rows that can’t be selected, like ones the person doesn’t have permission to change. The row still opens; only its checkbox is disabled.
122
+
123
+ ### Pagination
124
+
125
+ Long lists show one page at a time. Pass the size of the whole result set as `resultCount`, so the count and screen readers describe all of it, not just this page.
126
+
127
+ | Type | Use when |
128
+ | --------------------------- | -------------------------------------------------------------------------------------------------- |
129
+ | Numbered pages (`"paged"`) | The default. The total is known. Set `totalPages`; controls show once there are two or more pages. |
130
+ | Previous/Next (`"indexed"`) | The total isn’t known, so the list can only be stepped through. The controls always show. |
131
+
132
+ - Changing the search, filters, sort or view goes back to the first page, since the old page number no longer means anything.
133
+
134
+ ### Content
135
+
136
+ - **Column headers:** 1–3 words, sentence case, no ending punctuation.
137
+ - **Result noun:** the plural people would use, like “people” or “donations”, not “results” or “records”.
138
+ - **Empty state:** say what’s missing and why. When filters are applied, say that nothing matches and point to the filters, rather than saying there’s nothing to show.
139
+ - **View names:** 1–3 words, sentence case, named for what the view shows.
140
+ - **Capitalization:** sentence case everywhere; capitalize only the first word and proper nouns.
141
+
142
+ ### State usage
143
+
144
+ Every search, filter, sort, view or page change loads new rows, so these states come up often.
145
+
146
+ - **Loading:** set `loadingState="loading"` while any request the person started is in flight. Rows already on screen stay, with a spinner over them, so the table doesn’t go blank. Leave it `"idle"` for refreshes they didn’t start, like polling.
147
+ - **Empty:** `emptyState` shows when `data` is empty. Make it match why: no records yet, or no records that match the filters.
148
+ - **Error:** set `loadingState="error"` when the rows can’t load, with an `errorState` that says what to try next.
149
+ - **Disabled rows:** use `disabledKeys` for rows that can’t be selected, like ones the person doesn’t have permission to change.
150
+
151
+ ### Implementation notes
152
+
153
+ The table shows what it’s given. It doesn’t search, filter, sort or page the rows itself.
154
+
155
+ - **Controlled state:** `activeFilters`, `sortBy`, `visibleColumnNames`, `currentPage` and `selectedKeys` are all controlled. When someone changes the search, a filter, the sort, a view or the page, the table reports it through the matching callback; store the new value, pass it back in, and load the matching rows. Until the rows arrive, the chips update but the rows don’t. Set up filters with the Filters reference.
156
+ - **Saved views:** set up the Rails side with tapestry-rails, then spread its `data_table_props` and `useSavedViewsClient` onto the table. See Saved views.
157
+ - **Numbered pages:** pass only the current page’s rows as `data`, set `totalPages` and `currentPage`, and load the page `onPageChange` reports. After a filter, search, sort or view change, it reports page 1.
158
+ - **Previous/Next:** set `paginationType="indexed"` with `hasPreviousPage`, `hasNextPage`, `onPreviousPageClick` and `onNextPageClick`. The table can’t go back to the first page itself, so reset the cursor when the filters or sort change.
package/docs/llms.txt CHANGED
@@ -6,6 +6,9 @@ Before building UI, find the component whose "use when" matches what you're buil
6
6
 
7
7
  ## Components
8
8
 
9
+ - [DataTable](components/DataTable.md): showing a list of records people scan, sort, filter or act on, like people, groups or donations; a list that needs search, filters, saved views, pagination or bulk actions; comparing the same fields across many items in columns
10
+ - `import { DataTable } from "@planningcenter/tapestry/unstable"`
11
+ - Props: ../dist/components/DataTable/DataTable.d.ts
9
12
  - [ButtonGroup](components/button-group.md): two or more related actions that belong together, like a bulk-action bar; joining buttons into one control with shared borders
10
13
  - `import { ButtonGroup } from "@planningcenter/tapestry"`
11
14
  - Props: ../dist/components/button-group/ButtonGroup.d.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@planningcenter/tapestry",
3
- "version": "4.14.0",
3
+ "version": "4.15.0-rc.0",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -91,6 +91,7 @@
91
91
  "@types/postcss-import": "^14.0.3",
92
92
  "@types/react": "^18.3.3",
93
93
  "@types/react-dom": "^18.3.0",
94
+ "@types/use-sync-external-store": "^1.7.0",
94
95
  "@vitejs/plugin-react-swc": "^3.5.0",
95
96
  "autoprefixer": "^10.4.21",
96
97
  "concurrently": "^9.1.2",
@@ -139,7 +140,8 @@
139
140
  "lodash": "^4.17.21",
140
141
  "react-aria": "3.51.0",
141
142
  "react-aria-components": "1.20.0",
142
- "react-stately": "3.49.0"
143
+ "react-stately": "3.49.0",
144
+ "use-sync-external-store": "^1.7.0"
143
145
  },
144
- "gitHead": "db9eab8817118e31eabd7970737ab628e7898abe"
146
+ "gitHead": "7336ed1b71a8c9708b6400a070f3c82f098809d4"
145
147
  }