pdap-design-system 2.7.0-beta.3 → 2.7.0-beta.5

package/README.md

@@ -120,24 +120,25 @@ Use these [brand assets](https://docs.pdap.io/meta/about/staff/brand-assets). Us
 
 ## Scripts reference
 
-Script         | What it does
--------------- | -------------------------------------------------------
-`_commit`      | Create conventional commits
-`build`        | Builds the library
-`build:watch`  | Builds the library and watches for file changes
-`ci`           | Remove all generated files and re-installs deps
-`clean`        | Remove all generated files (except `package-lock.json`)
-`clean:deps`   | Remove node_modules directory
-`clean:build`  | Remove dist directory
-`clean:test`   | Remove testing coverage reports
-`lint`         | Lint everything
-`lint:es`      | Lint `ts` and `vue` with `eslint`
-`lint:css`     | Lint `css` and `vue` with `stylelint`
-`lint:ts`      | Lint `ts` with `tsc`
-`test`         | Run all test suites
-`test:changed` | Run only test suites affected by changed files
-`typecheck`    | Run type check on all `ts` and `vue` files
-`dev`          | Run demo app to check visual changes to components
+| Script         | What it does                                                            |
+| -------------- | ----------------------------------------------------------------------- |
+| `_commit`      | Create conventional commits                                             |
+| `build`        | Builds the library                                                      |
+| `build:watch`  | Builds the library and watches for file changes                         |
+| `ci`           | Remove all generated files and re-installs deps                         |
+| `clean`        | Remove all generated files (except `package-lock.json`)                 |
+| `clean:deps`   | Remove node_modules directory                                           |
+| `clean:build`  | Remove dist directory                                                   |
+| `clean:test`   | Remove testing coverage reports                                         |
+| `lint`         | Lint everything                                                         |
+| `lint:es`      | Lint `ts` and `vue` with `eslint`                                       |
+| `lint:css`     | Lint `css` and `vue` with `stylelint`                                   |
+| `lint:ts`      | Lint `ts` with `tsc`                                                    |
+| `test`         | Run all test suites                                                     |
+| `test:changed` | Run only test suites affected by changed files                          |
+| `typecheck`    | Run type check on all `ts` and `vue` files                              |
+| `dev`          | Run demo app to check visual changes to components                      |
+| `docs`         | Run script to automatically aggregate links to component `README` files |
 
 _n.b. There are some other scripts defined in the `package.json` `"scripts"` field, but they are mostly for CI or cleanup post-build, etc. You shouldn't need them._
 

package/dist/components/Breadcrumbs/PdapBreadcrumbs.vue.d.ts

@@ -1,2 +1,11 @@
+/**
+ * # `Breadcrumbs`
+ *
+ * Renders a hierarchy of matching links for all paths matching the current path.
+ *
+ * The rendered text of each link will default to the `name` value in each matching route's object, unless `meta.breadcrumbText` is set.
+ *
+ *
+ */
 declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{}>>, {}, {}>;
 export default _default;

package/dist/components/Breadcrumbs/index.d.ts

@@ -1,2 +1 @@
-import PdapBreadcrumbs from './PdapBreadcrumbs.vue';
-export { PdapBreadcrumbs as Breadcrumbs };
+export { default as Breadcrumbs } from './PdapBreadcrumbs.vue';

package/dist/components/Button/PdapButton.vue.d.ts

@@ -1,4 +1,13 @@
 import { PdapButtonProps } from './types';
+/**
+ * # `Button`
+ * Styled button with PDAP branding. DOM attributes are forwarded to the HTML element, and most functionality works well this way.
+ *
+ * ## Props
+ * @prop {'primary' | 'secondary' | 'tertiary'} intent controls the styling of the button
+ * @prop {boolean} isLoading loading state of button
+ *
+ */
 declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapButtonProps>, {
     intent: string;
     isLoading: boolean;

package/dist/components/Button/index.d.ts

@@ -1,2 +1 @@
-import PdapButton from './PdapButton.vue';
-export { PdapButton as Button };
+export { default as Button } from './PdapButton.vue';

package/dist/components/Dropdown/PdapDropdown.vue.d.ts

@@ -1,4 +1,14 @@
 import { PdapDropdownProps, PdapDropdownTriggerType } from './types';
+/**
+ * # `Dropdown`
+ * An accessible dropdown menu that can be triggered by click or hover and positioned in various placements. It provides keyboard accessibility features such as toggling the dropdown on enter/space and closing on escape.
+ *
+ * ## Props
+ * @prop {boolean} defaultOpen Controls the initial `isOpen` state
+ * @prop {boolean} disabled Disabled state (forwarded to trigger button)
+ * @prop {PdapDropdownTriggerType} triggerType `'press' | 'hover'`
+ *
+ */
 declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapDropdownProps>, {
     defaultOpen: boolean;
     disabled: boolean;

package/dist/components/ErrorBoundary/PdapErrorBoundary.vue.d.ts

@@ -1,18 +1,84 @@
-declare const _default: import("vue").DefineComponent<{
-    component: {
-        type: StringConstructor;
-        default: string;
-    };
-}, any, {
-    error: boolean;
-}, {}, {
-    interceptError(error: any): void;
-}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
-    component: {
-        type: StringConstructor;
-        default: string;
-    };
-}>>, {
+import { ComponentPublicInstance } from 'vue';
+import { PdapErrorBoundaryProps, PdapErrorEmitted } from './types';
+/**
+ * # `ErrorBoundary`
+ * Intercepts uncaught errors from its children and renders an error UI in place of its children.
+ *
+ * ## Props
+ * @prop {string} component Optional: the component to render as a fallback, defaults to 'div'
+ * @prop {PdapErrorBoundaryProps['onError']} onError Optional: callback to run on error, accepts two arguments, the error and the element (optional)
+ * @prop {Record<string, string>} params Optional: parameters to be forwarded to fallback
+ *
+ * ## Emits
+ * @emits onError includes object with `error`, and optionally `info` and `vm
+ *
+ * @example Top level
+ *
+ * <template>
+ * 	<AuthWrapper>
+ * 		<Header :logo-image-src="lockup" />
+ * 		<ErrorBoundary component="main">
+ * 			<router-view />
+ * 		</ErrorBoundary>
+ * 		<Footer :logo-image-src="acronym" />
+ * 	</AuthWrapper>
+ * </template>
+ *
+ * @example Within a component
+        <ErrorBoundary
+            class="col-span-full items-start"
+            component="div"
+            @on-error="({ error, vm, info }) => console.debug({ error, vm, info })"
+        >
+            <div class="col-span-full">
+                <p>
+                    This is the content that will render inside the error boundary if
+                    there is no error
+                </p>
+                <Button @click="triggerError">Click here to trigger error</Button>
+            </div>
+        </ErrorBoundary>
+ *
+ */
+declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapErrorBoundaryProps>, {
+    component: string;
+    onError: undefined;
+    params: undefined;
+}>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    onError: (args_0: PdapErrorEmitted) => void;
+}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapErrorBoundaryProps>, {
     component: string;
-}, {}>;
+    onError: undefined;
+    params: undefined;
+}>>> & {
+    onOnError?: ((args_0: PdapErrorEmitted) => any) | undefined;
+}, {
+    params: Record<string, string>;
+    onError: (error: Error, target?: ComponentPublicInstance | null | undefined, info?: string | undefined) => void;
+    component: string;
+}, {}>, {
+    default?(_: {}): any;
+}>;
 export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/ErrorBoundary/index.d.ts

@@ -0,0 +1 @@
+export { default as ErrorBoundary } from './PdapErrorBoundary.vue';

package/dist/components/ErrorBoundary/types.d.ts

@@ -0,0 +1,11 @@
+import { ComponentPublicInstance } from 'vue';
+export interface PdapErrorEmitted {
+    error: Error;
+    vm: ComponentPublicInstance | null;
+    info?: string;
+}
+export interface PdapErrorBoundaryProps {
+    component: string;
+    onError?: (error: Error, target?: ComponentPublicInstance | null | undefined, info?: string) => void;
+    params?: Record<string, string>;
+}

package/dist/components/Footer/PdapFooter.vue.d.ts

@@ -1,4 +1,12 @@
 import { PdapFooterProps } from './types';
+/**
+ * # `Footer`
+ *
+ * ## Props
+ * @prop {string} logoImageSrc Src for the PDAP logo image to be displayed
+ * @prop {string } logoImageAnchorPath Path for the link that wraps the PDAP logo image
+ *
+ */
 declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapFooterProps>, {
     logoImageSrc: string;
     logoImageAnchorPath: string;

package/dist/components/Form/PdapForm.vue.d.ts

@@ -1,6 +1,109 @@
 import { PdapFormProps } from './types';
-declare const v$: import("vue").Ref<import("@vuelidate/core").Validation<{}, Record<string, string>>>;
-export type VuelidateInstance = typeof v$.value;
+/**
+ * # `Form`
+ * The `Form` component is powerful. All you need to do is pass a few props, and the component will generate inputs and render them in the UI, complete with customizable form validation and both form-level and input-level error states.
+ *
+ *
+ * ## Props
+ * @prop {string | undefined | null} error Error state. Only a non-falsy string results in a form-level error being displayed
+ * @prop {string} id Passed through to the `form` element as its `id`
+ * @prop {string} name Passed through to the `form` element as its `name`
+ * @prop {PdapFormSchema} schema Array of `PdapFormInputProps` objects.
+ *
+ * ## Notes
+ *
+ * - Form schema entries can look different depending on the type of input. We currently only use text inputs, so the example only displays these.
+ * - To properly submit the form, you must render a button with `type="submit"` _inside_ of the `Form` component.
+ * - `Form` emits a `submit` event and passes all values to the handler you pass to `on-submit`
+ * - Currently available form validations are defined by the `PdapFormValidators` interface:
+ *
+ * ```
+ * PdapFormValidators {
+ *   maxLength: {
+ *     message?: string;
+ *     value: number;
+ *   };
+ *   minLength: {
+ *     message?: string;
+ *     value: number;
+ *   };
+ *   required: {
+ *     message?: string;
+ *     value: boolean;
+ *   };
+ * }
+ * ```
+ *
+ *
+ * @example
+ *
+ * <template>
+ *  <Form :schema="formSchema" :on-submit="handleSubmit" id="test-form" name="data-request-form">
+ *    <Button intent="primary" type="submit">Click me</Button>
+ *  </Form>
+ * </template>
+ *
+ *
+ * <st>
+ * import { Button, Form, PdapInputTypes } from 'pdap-design-system';
+ *
+ * export default {
+ *  components: ['Button', 'Form'],
+ *  data() {
+ *    return {
+ *      formSchema: [
+ *        {
+ *          id: 'testfirstname',
+ *          name: 'firstName',
+ *          label: 'First Name',
+ *          type: 'text',
+ *          placeholder: 'John',
+ *          value: '',
+ *          validators: {
+ *            minLength: {
+ *              value: 3
+ *            },
+ *            required: {
+ *              message: 'Please provide this information',
+ *              value: true
+ *            }
+ *          },
+ *        },
+ *        {
+ *          id: 'testlastname',
+ *          name: 'lastName',
+ *          label: 'Last Name',
+ *          type: 'text',
+ *          placeholder: 'Doe',
+ *          value: '',
+ *          validators: {
+ *            minLength: {
+ *              value: 3
+ *            },
+ *            maxLength: {
+ *              message: 'A thousand characters for your surname? Are you a bot?',
+ *              value: 999
+ *            },
+ *          },
+ *        {
+ *          id: 'ice-cream',
+ *          name: 'iceCream',
+ *          label: 'Do you like ice cream?',
+ *          type: 'checkbox',
+ *          defaultChecked: true,
+ *        }
+ *      ]
+ *    }
+ *  },
+ *  methods: {
+ *    handleSubmit: async function(data) {
+ *      await doRequestStuff(data);
+ *      this.$router.push('/')
+ *    }
+ *  }
+ *}
+ * </scriptt>
+ */
 declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapFormProps>, {
     error: null;
 }>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {

package/dist/components/Header/PdapHeader.vue.d.ts

@@ -1,4 +1,15 @@
 import { PdapHeaderProps } from './types';
+/**
+ * # `Header`
+ *
+ * ## Props
+ * @prop {string} logoImageSrc Src for the PDAP logo image to be displayed
+ * @prop {string } logoImageAnchorPath Path for the link that wraps the PDAP logo image
+ *
+ * ## Notes
+ * The `Header` component does not require any props to be passed. But keep in mind that it is responsible for rendering the `Nav` component. Consuming applications will need to `provide` an array of nav links -- **there are no defaults for this**, you must `provide` these links either 1\. in a layout component (see example below), at the route level, or at the app level. This allows for flexibility in which links are rendered on which routes
+ *
+ */
 declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapHeaderProps>, {
     logoImageSrc: string;
     logoImageAnchorPath: string;

package/dist/components/Nav/PdapNav.vue.d.ts

@@ -1,4 +1,41 @@
 import { PdapNavProps } from './types';
+/**
+ * # `Nav`
+ *
+ * ## Notes
+ * You do not need to render `Nav` directly. `Header` takes care of that. But you do need to `provide` nav link data from a parent component. This allows for nav links to be dynamic depending on where `Header` is rendered.
+ *
+ * @example
+ *
+ *<template>
+ *  <Header />
+ *  <router-view />
+ *  <Footer />
+ *</template>
+ *
+ *
+ *<scriptt>
+ *import { Footer, Header } from 'pdap-design-system';
+ *import { RouterView } from 'vue-router';
+ *
+ *...
+ *
+ *export default {
+ *  name: 'Layout',
+ *  components: ['Footer', 'Header'],
+ *  provide: {
+ *    navLinks: [
+ *      { path: '/', text: 'Home', method: 'path' },
+ *      { path: '/a', text: 'a', method: 'path' },
+ *      { path: '/b', text: 'b', method: 'path' },
+ *      { path: '/c', text: 'c', method: 'path' },
+ *      { href: 'https://www.google.com', text: 'Go to Google', method: 'href' },
+ *    ]
+ *  }
+ *  ...
+ *}
+ *</scriptt>
+ */
 declare const _default: import("vue").DefineComponent<__VLS_TypePropsToRuntimeProps<PdapNavProps>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<PdapNavProps>>>, {}, {}>;
 export default _default;
 type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;

package/dist/components/QuickSearchForm/QuickSearchForm.vue.d.ts

@@ -1,3 +1,17 @@
+/**
+ * # QuickSearchForm
+ * Renders a form to search the API `/search` endpoint with a search term and a location.
+ *
+ * ## Notes
+ *
+ * The different `mode` prop values result the following base url values in the eventual navigation
+ *
+ * | value    | base url                          |
+ * | -------- | --------------------------------- |
+ * | `'dev'`  | `'https://data-sources.pdap.dev'` |
+ * | `'prod'` | `'https://data-sources.pdap.io'`  |
+ *
+ */
 declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<{
     baseUrlForRedirect: string;
 }>, {

package/dist/components/{FlexContainer/FlexContainer.vue.d.ts → Spinner/PdapSpinner.vue.d.ts}

@@ -1,17 +1,20 @@
-import { PdapFlexContainerProps } from './types';
-/** @deprecated Please use TailwindCSS class instead */
-declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapFlexContainerProps>, {
-    alignment: string;
-    component: string;
-}>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapFlexContainerProps>, {
-    alignment: string;
-    component: string;
+import { PdapSpinnerProps } from './types';
+declare const _default: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapSpinnerProps>, {
+    color: string;
+    size: number;
+    text: string;
+    show: boolean;
+}>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<PdapSpinnerProps>, {
+    color: string;
+    size: number;
+    text: string;
+    show: boolean;
 }>>>, {
-    component: string;
-    alignment: "center" | "start";
-}, {}>, {
-    default?(_: {}): any;
-}>;
+    text: string;
+    size: number;
+    color: string;
+    show: boolean;
+}, {}>;
 export default _default;
 type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
 type __VLS_TypePropsToRuntimeProps<T> = {
@@ -30,8 +33,3 @@ type __VLS_WithDefaults<P, D> = {
 type __VLS_Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
-type __VLS_WithTemplateSlots<T, S> = T & {
-    new (): {
-        $slots: S;
-    };
-};

package/dist/components/Spinner/index.d.ts

@@ -0,0 +1 @@
+export { default as Spinner } from './PdapSpinner.vue';

package/dist/components/Spinner/types.d.ts

@@ -0,0 +1,6 @@
+export interface PdapSpinnerProps {
+    color?: string;
+    size?: number;
+    text?: string;
+    show: boolean;
+}

package/dist/components/TileIcon/TileIcon.vue.d.ts

@@ -1,4 +1,7 @@
 import { PdapTileIconProps } from './types';
+/**
+ * @deprecated unused
+ */
 declare const _default: import("vue").DefineComponent<__VLS_TypePropsToRuntimeProps<PdapTileIconProps>, {}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<PdapTileIconProps>>>, {}, {}>;
 export default _default;
 type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;

package/dist/components/index.d.ts

@@ -1,9 +1,7 @@
 export { Button } from './Button';
-export { FlexContainer } from './FlexContainer';
+export { ErrorBoundary } from './ErrorBoundary';
 export { Footer } from './Footer';
 export { Form } from './Form';
-export { GridContainer } from './GridContainer';
-export { GridItem } from './GridItem';
 export { Input } from './Input';
 export { Header } from './Header';
 export { Nav } from './Nav';
@@ -11,3 +9,4 @@ export { QuickSearchForm } from './QuickSearchForm';
 export { TileIcon } from './TileIcon';
 export { Dropdown } from './Dropdown';
 export { Breadcrumbs } from './Breadcrumbs';
+export { Spinner } from './Spinner';