feat(utils): add `truncate` utility function

[andipaetzold]

Purpose of PR

Introduce a new utility function truncate.

truncate is a utility function that truncates a given string from the left, right or the middle. The removed characters are replaced with a customizable string.

PR Checklist

• [x] I have read the relevant readme.md file(s)
• [x] All commits follow our Git commit message convention
• [x] Tests are added/updated/not required
• [x] Tests are passing
• [x] Storybook stories are added/updated/not required
• [x] Usage notes are added/updated/not required
• [x] Has been tested based on Contentful's browser support
• [x] Doesn't contain any sensitive information

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
forma-36	✅ Ready (Inspect)	Visit Preview	Jun 17, 2024 1:34pm

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 558a312d9fec6ee3ae3c858957c47e9b052f6b4a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

| Name | Type | | --------------------- | ----- | | @contentful/f36-utils | Minor |

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions[bot]]

size-limit report 📦

Path	Size	Loading time (3g)	Running time (snapdragon)	Total time
CommonJS	135.79 KB (0%)	2.8 s (0%)	616 ms (-34.43% 🔽)	3.4 s
Module	132.02 KB (-0.03% 🔽)	2.7 s (-0.03% 🔽)	754 ms (-4.56% 🔽)	3.4 s

[andipaetzold]

Sorry if the wording of the ticket was imprecise, but we want to always keep 6 characters on each side of the truncation.

I built the method in a way that matches the expectations that I assume the user of this function has. Imo, when a user truncates a string, they want to truncate that string to a specific length: The number of characters they have available. They don't care that much about the number of characters are before and after the ellipsis. Their goal is to get the string down to a max length. By ignoring the size of the replacement, the user has to do math themselves to get the string to a specific length.

Would you envision the implementation to look like this?

function truncateMiddle(
  str: string,
  maxLength: number,
  replacement = '…',
) {
  if (str.length <= 2 * maxLength) {
    return str;
  }

  return `${str.slice(0, maxLength)}${replacement}${str.slice(-maxLength)}`;
}

Maybe this should be configurable as well to be more generally useful?

What do you want to configure?

[denkristoffer]

@andipaetzold

What do you want to configure?

The number of characters shown before and after the cut.

I do agree with you about what the expectation for a function such as this would be from a user's perspective. At the same time we currently need to always show 6 characters on each side of the cut. I will get back to you once I have confirmed the final behaviour with Daniel.

[andipaetzold]

I updated the PR to allow defining the string length at the start and end.

FAQ:

• Why options object? Positional arguments with identical types are dangerous, typing start and end is more explicit
• Why start and not startLength - you rename it anyway? It's shorter
• Why allow optional? Why not 🤷 That way, the method can also be used to truncate at the end. Maybe worth renaming it to just truncate then?
• Why is str not part of the options object? Because it's a required argument.

[damann]

@stephanLeece @massao First of all thanks for picking up on this idea! Are the numbers you can set minimum or absolute characters? I imagined it to be the later.

[andipaetzold]

@damann

First of all thanks for picking up on this idea! Are the numbers you can set minimum or absolute characters? I imagined it to be the later.

The numbers passed in via the options are the number of characters of the original string that should remain in the truncated string. If the original string is 5 characters, but you want to keep 3 at the front and 3 at the back, no truncation is done and the original string is returned.

[damann]

The numbers passed in via the options are the number of characters of the original string that should remain in the truncated string. If the original string is 5 characters, but you want to keep 3 at the front and 3 at the back, no truncation is done and the original string is returned.

So, the truncation would stop at the specified number of characters, but it would also allow for more characters depending on the available space?

[denkristoffer]

The numbers passed in via the options are the number of characters of the original string that should remain in the truncated string. If the original string is 5 characters, but you want to keep 3 at the front and 3 at the back, no truncation is done and the original string is returned.

So, the truncation would stop at the specified number of characters, but it would also allow for more characters depending on the available space?

@damann No, the handling of hiding and showing text will have to happen in the web app itself. This function is a helper to do that.