npm package: @izumisy-tailor/fabrix-appshell
Description: This is a package that helps users create frontend application using Fabrix on Next.js
Latest version: 0.3.0

# Fabrix AppShell

This is a package that helps users create frontend application using Fabrix on Next.js

## Quick start

The quickest way to start using fabrix-appshell is to use template with create-react-app.

```bash
npx create-next-app@latest my-fabrix-app --use-pnpm -e https://github.com/IzumiSy/nextjs-fabrix-appshell-template
```

This includes the initial setup with the machine user authentication. Follow [the instruction in the repo](https://github.com/IzumiSy/nextjs-fabrix-appshell-template).

### Install manually

You also have an option to install a package to start fabrix-appshell without the template.

```bash
pnpm install --save @izumisy-tailor/fabrix-appshell
```

## Usage 

AppShell is expected to be mounted on an optional catch-all segments.

Copy the code below to your `src/app/dashboard/[[...props]]/page.tsx` if you are using App Router with src directory.

```tsx
"use client";
import { AppShell, AppShellPageParams } from "@izumisy-tailor/fabrix-appshell";
import { useParams } from "next/navigation";
import "@izumisy-tailor/fabrix-appshell/styles";

const Page = () => {
  const params = useParams<AppShellPageParams>();

  return (
    <AppShell
      url="https://your-own-api.example.com/graphql"
      pageParams={params}
      configurations={{
        resources: {
          /* add your resource definition here */
        },
      }}
    />
  );
}

export default Page;
```

### Define resources

To add new resource in your AppShell, we have a scaffolding function that is `defineCRUDResource`.

```ts
// contact.ts
import { defineCRUDResource, gql } from "@izumisy-tailor/fabrix-appshell";

export export contactResource = defineCRUDResource({
  title: "Contacts",
  listQuery: gql`
    query listContacts {
      contacts {
        edges {
          node {
            id
            company
            city
            email
            name
            phone
          }
        }
      }
    }
  `,
  props: {},
});
```

The GraphQL query given to `listQuery` is used as the data source of the table view.

Then, add the resource to the `AppShell` in your app.

```diff
 "use client";
 import { AppShell, AppShellPageParams } from "@izumisy-tailor/fabrix-appshell";
 import { useParams } from "next/navigation";
+import { contactResource } from "./contact.ts";
 import "@izumisy-tailor/fabrix-appshell/styles";

 const Page = () => {
   const params = useParams<AppShellPageParams>();

   return (
     <AppShell
       url="https://your-own-api.example.com/graphql"
       pageParams={params}
       configurations={{
         resources: {
+          contactResource
         },
       }}
     />
   );
 }
```

All done! Now, open your app to see how fabrix works for you.

## API

### `AppShell`

An entry point component to render your app with appshell that has header, sidebar, and content.

### `defineCRUDResource`

A helper function to create template page that has a full-fledged table component

```tsx
import { defineCRUDResource, gql } from "@izumisy-tailor/fabrix-appshell";

export default defineCRUDResource({
  // Page title
  title: "Contacts",

  // Page category (used to group pages in the sidebar)
  category: "Table",

  // A GraphQL collection query for the table
  listQuery: gql`
    query listContacts {
      contacts {
        edges {
          node {
            id
            company
            city
            email
            name
            phone
          }
        }
      }
    }
  `,

  // Custom props (see type definition)
  props: {},
});
```

### `defineResource`

A function to define a resource that uses ReactNode.

```tsx
import { defineResource } from "@izumisy-tailor/fabrix-appshell";

export default defineResource({
  type: "component",
  title: "Custom",
  category: "Pages",
  component: () => {
    return <div>Here is a custom page</div>;
  },
});
```