Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[EXPERIMENTAL] Provide addon-defined template types for Glint #968

Merged
merged 36 commits into from
Dec 14, 2022

Conversation

kpfefferle
Copy link
Member

@kpfefferle kpfefferle commented Oct 31, 2022

This PR adds Glint template types for Ember Table to be published with the addon package. It enables consumers to define the shape of their table rows and columns and then enforces that the arguments passed in to Ember Table matches those types. All publicly documented arguments are also enforced to be the appropriate type. Yielded values (rows, columns, cell values) are yielded with respective types as well (with cell values yielded as a union of possible types).

These Glint types are isolated to the /types/ directory in the repo, so they should not affect any of the functional addon code.

Documentation - as added to the README

EXPERIMENTAL: Using Ember Table with Glint

Ember Table provides experimental Glint types defined in the /types/ directory.
These types may change at any time and are NOT covered by Ember Table's semantic versioning.
They are intended to support standard documented usage of Ember Table and do not attempt to type the internals of the Ember Table addon.
If you are using Ember Table in a more advanced way (such as extending Ember Table components), you will still need to define your own types for those use cases.

To use the provided Ember Table types for Glint:

  1. Define a type interface for your row contents. If your columns contain additional custom attributes, you can type those as well. Ember Table provides default interfaces that can be extended for this purpose.
  2. Extend the base Ember Table component passing in your row and (optional) column interfaces as generics.
  3. Use this extended version of the Ember Table component in your template.

For example:

// my-table-component.ts
import type { EmberTableColumn, EmberTableRow } from 'ember-table';
import EmberTableComponent from 'ember-table/components/ember-table/component';

interface MyTableColumn extends EmberTableColumn {
  // Add any custom column attribute types here (optional)
}

interface MyTableRow extends EmberTableRow {
  // Add the attributes and types for your table rows here
}

class MyEmberTableComponent extends EmberTableComponent<MyTableRow, MyTableColumn> {}

export default class MyTableComponent extends Component<MyTableComponentSignature> {
  emberTableComponent = MyEmberTableComponent;
}
{{! my-table-component.hbs }}
<this.emberTableComponent as |t|>
  {{! Use Ember Table as usual. Row and column arguments will be enforced to match the appropriate types. }}
  {{! Yielded items (rows, columns) will be typed according to the specified interfaces. }}
  {{! Cell values will be typed as a union of all defined row attribute types. }}
</this.emberTableComponent>

@kpfefferle
Copy link
Member Author

Should migrate to the new recommendation for exporting registry entries: typed-ember/glint#446

@kpfefferle kpfefferle force-pushed the kpfefferle/glint-types branch 2 times, most recently from b421280 to f60c9b0 Compare November 28, 2022 19:00
@kpfefferle kpfefferle force-pushed the kpfefferle/glint-types branch from f60c9b0 to d7e607d Compare November 28, 2022 19:01
@kpfefferle kpfefferle force-pushed the kpfefferle/glint-types branch from d7e607d to 4821d84 Compare November 28, 2022 19:03
@kpfefferle kpfefferle force-pushed the kpfefferle/glint-types branch from 2646171 to 8025e09 Compare November 28, 2022 20:15
@@ -87,7 +87,7 @@ export default Component.extend({
sorts: defaultTo(() => []),

/**
An optional sort. If not specified, defaults to <sortMultiple>, which
An optional sort. If not specified, defaults to `<sortMultiple>`, which
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While typing documented arguments, I noticed that <sortMultiple> is not rendered in the API docs without the backticks

Comment on lines -198 to -203
/**
An action that is sent when sorts is updated
@argument onHeaderAction
@type Action?
*/
onHeaderAction: null,
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This argument appears to be completely unused - I couldn't find reference to it anywhere else in the codebase (and the comment is obviously inaccurately copied from onUpdateSorts below).

@kpfefferle
Copy link
Member Author

Released as 5.0.1-0

@kpfefferle kpfefferle requested a review from a team December 12, 2022 19:23
@kpfefferle kpfefferle marked this pull request as ready for review December 12, 2022 19:23
@kpfefferle kpfefferle mentioned this pull request Dec 12, 2022
{{! Yielded items (rows, columns) will be typed according to the specified interfaces. }}
{{! Cell values will be typed as a union of all defined row attribute types. }}
</this.emberTableComponent>
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for these docs 🙇

@mixonic
Copy link
Member

mixonic commented Dec 14, 2022

Amazing.

@kpfefferle kpfefferle merged commit 3baeabb into master Dec 14, 2022
@kpfefferle kpfefferle deleted the kpfefferle/glint-types branch December 14, 2022 16:11
@kpfefferle
Copy link
Member Author

Released as 5.0.1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants