feat(docs,dgeni,daffio): add storefront design docs

[griest024]

PR Checklist

• Commit message follows our contributing guidelines
• Tests added/updated (for bug fixes/features)
• Documentation added/updated (for bug fixes/features)

PR Type

• Bug fix
• Feature
• Style update
• Refactor
• Test
• Build
• CI
• Docs
• Performance
• Other (please describe)

Current behavior

Fixes: #4266
Fixes: #4265

New behavior

Breaking change?

• Yes
• No

Additional context

[xelaint]

Todo:

• Add custom overview page

[xelaint]

@griest024 Is there a way to extract the Design link from DaffioNavLink so I can add a different UI to it?

[xelaint]

should storefront have it's own routes? i'm having a hard time figuring out where I should be putting the storefront overview page.

[griest024]

yes, I've made them more reusable for storefront and added the overview route

[griest024]

@griest024 Is there a way to extract the Design link from DaffioNavLink so I can add a different UI to it?

You want a nav link to be an arbitrary component?

[xelaint]

@griest024 Is there a way to extract the Design link from DaffioNavLink so I can add a different UI to it?

You want a nav link to be an arbitrary component?

Yes. The Design link needs to be able to be a button that opens up a daff-menu.

[xelaint]

Ordering needs to be fixed. Overview should be first.

[griest024]

Ordering needs to be fixed. Overview should be first.

this can be controlled by an index.json file in the guides folder. See 0f8d882 as an example.

[griest024]

@griest024 Is there a way to extract the Design link from DaffioNavLink so I can add a different UI to it?

You want a nav link to be an arbitrary component?

Yes. The Design link needs to be able to be a button that opens up a daff-menu.

will this need to be different in the sidebar? The sidebar nav links are rendered as

<a daff-list-item [routerLink]="link.url">{{ link.title }}</a>

in the sidebar but

<a daffioHeaderItem [routerLink]="link.url" [active]="rla.isActive" routerLinkActive #rla="routerLinkActive">{{ link.title }}</a>

in the header. Will these need different components for the design link?

[xelaint]

@griest024 Is there a way to extract the Design link from DaffioNavLink so I can add a different UI to it?

You want a nav link to be an arbitrary component?

Yes. The Design link needs to be able to be a button that opens up a daff-menu.

will this need to be different in the sidebar? The sidebar nav links are rendered as

<a daff-list-item [routerLink]="link.url">{{ link.title }}</a>

in the sidebar but

<a daffioHeaderItem [routerLink]="link.url" [active]="rla.isActive" routerLinkActive #rla="routerLinkActive">{{ link.title }}</a>

in the header. Will these need different components for the design link?

I think the sidebar may need to turn into a tree where Design opens up to two option of: Components and Storefront UI

[griest024]

@griest024 Is there a way to extract the Design link from DaffioNavLink so I can add a different UI to it?

You want a nav link to be an arbitrary component?

Yes. The Design link needs to be able to be a button that opens up a daff-menu.

will this need to be different in the sidebar? The sidebar nav links are rendered as

<a daff-list-item [routerLink]="link.url">{{ link.title }}</a>

in the sidebar but

<a daffioHeaderItem [routerLink]="link.url" [active]="rla.isActive" routerLinkActive #rla="routerLinkActive">{{ link.title }}</a>

in the header. Will these need different components for the design link?

I think the sidebar may need to turn into a tree where Design opens up to two option of: Components and Storefront UI

okay I've added some basic support for it. the component will the type input to tell if it's a header or a link.

[xelaint]

I think there may have been a misunderstanding on what I'm hoping the UI would be. I'm confused why DaffioNavLinkComponent had to be created to render a header link or a sidebar link and how that solves my request of being able to add specific styling to a specific header item in the nav.

My original comment about extracting out the link from DaffioNavLink is in reference to this:

links$: Observable<Array<DaffioNavLink>>;, not to create a separate nav link component.

My request was (from the original marketing header), how am I able to add [daffMenuActivator] to the Design header item so that it can open up a menu?

This is how the header links are currently generated:

<ng-container daffioHeaderItem>
      @if (link.external) {
        <a daffioHeaderItem [href]="link.url" target="_blank">{{link.title}}</a>
      } @else {
        <a daffioHeaderItem [routerLink]="link.url" [active]="rla.isActive" routerLinkActive #rla="routerLinkActive">{{ link.title }}</a>
      }
    </ng-container>

I currently don't see a way of pulling the Design header item out in order to add specific UI to it.

[griest024]

I think there may have been a misunderstanding on what I'm hoping the UI would be. I'm confused why DaffioNavLinkComponent had to be created to render a header link or a sidebar link and how that solves my request of being able to add specific styling to a specific header item in the nav.

My original comment about extracting out the link from DaffioNavLink is in reference to this:

links$: Observable<Array<DaffioNavLink>>;, not to create a separate nav link component.

My request was (from the original marketing header), how am I able to add [daffMenuActivator] to the Design header item so that it can open up a menu?

This is how the header links are currently generated:

<ng-container daffioHeaderItem>
      @if (link.external) {
        <a daffioHeaderItem [href]="link.url" target="_blank">{{link.title}}</a>
      } @else {
        <a daffioHeaderItem [routerLink]="link.url" [active]="rla.isActive" routerLinkActive #rla="routerLinkActive">{{ link.title }}</a>
      }
    </ng-container>

I currently don't see a way of pulling the Design header item out in order to add specific UI to it.

The crucial change for you is 5bfacb4#diff-78e1e01dcea1af5d8549dfa9e46bcc5d90b0068d5e2602e8b42de6d91009acc9. The array of nav links now accepts a component type in place of the original plain object. This should allow you to render anything you want.

The reason that I created DaffioNavLinkComponent was to encapsulate the nav link rendering logic which was getting complicated with the addition of supporting components.

What you need to do is create a component and replace this line:

daffodil/apps/daffio/src/app/docs/docs.routes.ts

Line 35 in f39ab75

{ url: `/${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}`, title: 'Design' },

with your new component. If you're still unsure of how to proceed, I will create a stub component loaded up in the correct places to which you can add custom design nav link logic.

[xelaint]

I think there may have been a misunderstanding on what I'm hoping the UI would be. I'm confused why DaffioNavLinkComponent had to be created to render a header link or a sidebar link and how that solves my request of being able to add specific styling to a specific header item in the nav.
My original comment about extracting out the link from DaffioNavLink is in reference to this:
links$: Observable<Array<DaffioNavLink>>;, not to create a separate nav link component.
My request was (from the original marketing header), how am I able to add [daffMenuActivator] to the Design header item so that it can open up a menu?
This is how the header links are currently generated:

<ng-container daffioHeaderItem>
      @if (link.external) {
        <a daffioHeaderItem [href]="link.url" target="_blank">{{link.title}}</a>
      } @else {
        <a daffioHeaderItem [routerLink]="link.url" [active]="rla.isActive" routerLinkActive #rla="routerLinkActive">{{ link.title }}</a>
      }
    </ng-container>

I currently don't see a way of pulling the Design header item out in order to add specific UI to it.

The crucial change for you is 5bfacb4#diff-78e1e01dcea1af5d8549dfa9e46bcc5d90b0068d5e2602e8b42de6d91009acc9. The array of nav links now accepts a component type in place of the original plain object. This should allow you to render anything you want.

The reason that I created DaffioNavLinkComponent was to encapsulate the nav link rendering logic which was getting complicated with the addition of supporting components.

What you need to do is create a component and replace this line:

daffodil/apps/daffio/src/app/docs/docs.routes.ts

Line 35 in f39ab75

{ url: `/${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}`, title: 'Design' },

with your new component. If you're still unsure of how to proceed, I will create a stub component loaded up in the correct places to which you can add custom design nav link logic.

Yeah, can you create a stub component? I'm still confused because Design will no longer be a link. It will be:

<button [daffMenuActivator]="designMenu">Design</button>

<ng-template #designMenu>
  <daff-menu>
    <a routerLink="/docs/design" daff-menu-item>
      Components
    </button>
    <a routerLink="/docs/storefront" daff-menu-item>
      Storefront UI
    </button>
  </daff-menu>
</ng-template>

[griest024]

@xelaint added: 62c6646

[xelaint]

@xelaint added: 62c6646

How do we get the sidebar to render a where Components and Storefront UI are child items of Design instead of using DaffioDocsDesignNavLinkComponent?

[griest024]

@xelaint added: 62c6646

How do we get the sidebar to render a where Components and Storefront UI are child items of Design instead of using DaffioDocsDesignNavLinkComponent?

check the value of type(), I added a switchcase to the template to demonstrate this. Will it work to just put multiple list items in the 'list' case?

[xelaint]

I tried (with claude's help) to remove the need for a separate link component and updated the sidebar body to use a tree. 7c37d12